Agent-Skills.md

Agent Skills: Design system workflow

>-

design-systemID: petrilahdelma/digitaltableteur/dt-design-system

Repository

petrilahdelma/digitaltableteur
PetriLahdelma
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/PetriLahdelma/digitaltableteur/tree/HEAD/.claude/skills/dt-design-system

Skill Files

Browse the full folder contents for dt-design-system.

Download Skill

Loading file tree…

.claude/skills/dt-design-system/SKILL.md

Skill Metadata

Name
dt-design-system
Description
>-

Design system workflow

Instructions

Step 1: Load context

  1. Read references/area-guide.md
  2. Before creating UI, run dt-use-existing-component or npm run find-component -- "your intent".
  3. Search for existing components before creating new ones:
rg -n "<SimilarName" nextjs-app/shared/components/
  1. For new components, open docs/LLM_COMPONENT_GENERATION_RULES.md by relevant section only — do not paste the full 12k-word doc into context.

Step 2: Scaffold (new component)

npm run new-component ComponentName

Expected output: folder under nextjs-app/shared/components/ComponentName/ with .tsx, .module.css, .stories.tsx, .test.tsx, .contract.json, .spec.md, .mdx, index.ts.

CRITICAL before finishing:

  • WIP badge on Storybook story until promoted
  • axe-core assertion in .test.tsx
  • EN / FI / SV keys if user-facing strings
  • Design tokens from variables.css — no hardcoded colors

Step 2.5: Storybook Controls quality (every story, every prop)

Every Controls-panel row must be deliberate — see the "Storybook Controls quality bar" table in nextjs-app/shared/components/AGENTS.md. Summary: real control + description + default summary for enums/booleans; control: "text" with a seeded "" arg for free strings (no "Set string" buttons); table: { disable: true } for handlers (action pane covers them) and ReactNode/ref props (no "Set object" buttons); table.category groups (Content/Appearance/Behavior/Accessibility/Advanced). Never blanket-fill argTypesProxyExempt — the validator errors on stale or variant-axis exemptions.

Step 3: Validate

npm run validate:components
npm test -- ComponentName

If validation fails, halt and fix reported contract/spec/MDX issues before proceeding.

Before pushing contract or component changes, also run the farm-parity contract gate (the pre-push hook enforces it too):

npm run build:tokens && npm run check:contract-props && npm run check:consumers

When a component detects an invalid prop combination at runtime (a dev warning, a prop that is silently ignored), encode it as a forbiddenCombos rule in the contract and run npm run validate:agent-usage -- --all --update-ratchet; see "Machine-checkable usage rules" in nextjs-app/shared/components/AGENTS.md.

check:contract-props compares contracts against freshly built agent blocks. Contracts with authored usage (doc-adopted) own their composesWith/prefersOver/forbiddenUse; only props are machine-checked for them. Props must be declared locally on the <Name>Props interface — a prop that only arrives via a native attribute extension (e.g. disabled) is invisible to the extractor and will be flagged stale.

Step 4: Promote (remove WIP badge)

Only when ALL pass:

  • Unit + axe tests green
  • npm run test:stories:smoke for the story
  • Full i18n coverage
  • Visual check in Storybook or via npx agent-browser

Ask the user before promoting contract status to stable.

Token changes

npm run build:tokens

Regenerates nextjs-app/shared/foundations/dist/agent-manifest.json.

@dt usage gate

Do not replace pattern-level <h*> / header chrome <button> with @dt/Title / @dt/Button unless explicitly requested — that changes typography and breaks section CSS. Fix heading levels only (h3 → h2) while keeping existing classes. npm run lint:dt-usage flags @/components/ui/* in app/, patterns, pages, and shared components (known shadcn debt allowlisted).

Agent / MCP discovery

  • CLI: npm run find-component -- "your intent"
  • Local MCP: npm run ds:mcp (stdio — see docs/DESIGN_SYSTEM_MCP.md)
  • HTTP: /mcp on production (design-system tools + consulting)

Examples

Example 1: New Button variant

User says: "Add a ghost variant to Button"

Actions:

  1. Load existing nextjs-app/shared/components/Button/
  2. Update Button.tsx, Button.module.css, Button.contract.json, Button.spec.md
  3. Add story variant + test coverage
  4. Run npm run validate:components && npm test -- Button

Example 2: New layout pattern

User says: "Create a pricing table pattern"

Actions:

  1. Check nextjs-app/shared/patterns/ for similar patterns
  2. Compose from @dt primitives (Title, Text, Card, Grid) — no raw <h2> or <p>
  3. Follow same contract/story/test structure as components
  4. Run validation gates

Troubleshooting

validate:components fails on contract

Cause: props in .tsx drifted from .contract.json or spec has open TODOs at beta+.

Solution: align contract schema with exported props; rewrite stub MDX/spec prose flagged in agent-manifest.json.

Storybook story missing WIP badge

Cause: scaffolder default removed manually.

Solution: restore WIP badge until a11y + visual + i18n gates pass.

Tests fail on axe violations

Cause: missing labels, contrast, or keyboard support.

Solution: fix a11y in component first; do not suppress axe rules without documented justification in spec.

Boundaries

  • MUST NOT use inline styles (except dynamic backgroundImage)
  • MUST NOT create single-file components outside folder structure
  • MUST NOT remove WIP badge without full verification gate
Design system workflow Skill | Agent Skills