Imported from keystone-ui/react (.claude/skills/contributing/SKILL.md). Install upstream with npx skills add keystone-ui/react --skill contributing. Copyright stays with the author.

Component Contributing Workflow

See CONTRIBUTING.md for the full guide.

Adding a New Component

Always start with the scaffolding command:

pnpm add:component MyComponent

This creates all files and updates all registries. Then follow the Storybook-first workflow:

1. Implement the component in packages/ui/src/{name}.tsx
2. Write Storybook stories in apps/storybook/stories/{name}.stories.tsx (primary dev surface)
3. Create Fumadocs demos in apps/docs/demos/{name}/ (3-6 simplified demos from stories)
4. Register demos in apps/docs/demos/index.ts
5. Write MDX docs in apps/docs/content/docs/components/{name}.mdx using <ComponentPreview name="{name}-{example}" />. For compound components (≥2 exported parts that nest), include a ## Composition ASCII tree after ## Usage — see Composition tree below.
6. LLMs.txt updates automatically (no manual step)
7. Sync the AI agent surface — see Sync the AI Agent Surface below

Adding a New Block

Blocks are full-page compositions, hand-registered (no pnpm add:block scaffolder yet). Workflow:

1. Author the source under apps/docs/demos/blocks/<name>.tsx (single-file) or apps/docs/demos/blocks/<name>/ (multi-file with index.tsx re-export).
2. Register the demo in apps/docs/demos/index.ts as "block-<name>": { component: ..., file: "blocks/<name>.tsx" }. The block-<name> key is what <BlockPreview name="block-<name>"> resolves against.
3. Generate the installable copy with pnpm sync:blocks. It rewrites the demo's imports (@keystoneui/react/x → @/components/ui/x, @keystoneui/react/utils → @/lib/utils, ./sibling → @/components/sibling, de-aliased lucide names) into registry/default/blocks/<name>/components/, then formats the result. Never hand-edit those files — pnpm lint:docs runs --check and fails when they drift from the demo. page.tsx is the exception: four hand-written lines, not generated.
4. Add the registry entry by hand-editing registry.json. The block item must include:
   • name, type: "registry:block", title, description
   • dependencies (npm packages) and registryDependencies (other registry items)
   • files[] with per-file types: registry:page (with target: "app/<slug>/page.tsx") for the page entry; registry:component for everything else
   • categories: [...] — see the taxonomy below. pnpm sync:registry warns if missing.
5. Write the MDX at apps/docs/content/docs/blocks/<name>.mdx. Required structure: install bash fence, <BlockPreview name="block-<name>">, ## Components Used with links to /docs/components/<primitive>. The lint at pnpm lint:docs blocks merge if any of these are missing or malformed. See apps/docs/content/docs/blocks/_block-template.mdx.
6. Regenerate backlinks with pnpm docs:backlinks — this auto-injects ## Related Blocks into every component MDX referenced under ## Components Used (idempotent, fenced).
7. Rebuild the registry with pnpm registry:build.

Block category taxonomy

Every block must carry at least one category. Current values in use:

When adding a new category, prefer single-word lowercase strings that mirror shadcn naming where any overlap exists (shadcn's own registry.json, at https://ui.shadcn.com/r/registry.json, is the reference). Document the new category in this table and in AGENTS.md → "Block Authoring".

Updating an Existing Component

API change (new/renamed prop, new sub-component)

1. Update component source
2. Update Storybook stories
3. Update Fumadocs demos if user-facing
4. Update MDX API Reference table
5. If a sub-component was added/removed/renamed: update the ## Composition ASCII tree in the MDX
6. Update _registry.ts if dependencies changed
7. Sync the AI agent surface (below) — if the change affects rules, conventions, or the public API the skill teaches

Visual/styling change

1. Update component source only
2. Storybook and Fumadocs demos auto-reflect
3. No agent-surface changes needed unless the styling change introduces a new rule (e.g., new transition, new token)

Description/copy change

1. Update MDX frontmatter or section text only
2. LLMs.txt auto-reflects on next deploy

Sync the AI Agent Surface

Three surfaces drift if not maintained explicitly. Run through this checklist after any component add or convention change.

When adding a brand-new component

Count policy. The component count is hardcoded in ~12 places. Only two state an exact number and both must be updated:

• skills/keystoneui-react/SKILL.md — the ## Component List heading.

• apps/docs/content/docs/(getting-started)/rtl.mdx — a ratio ("30 of its 56 components"), so recompute it rather than incrementing:

  ls packages/ui/src/*.tsx | grep -v '.test.tsx' | wc -l          # components
  grep -rlE '\b(ml-|mr-|pl-|pr-|left-|right-)' packages/ui/src/*.tsx \
    | grep -v test | wc -l                                        # with physical utilities

Everywhere else — README.md, the home page, the gallery, index.mdx, llms-utils.ts, mcp-server.mdx, the intro blog post — says 50+ and should stay that way. Bumping a dozen numbers per component is how they end up disagreeing with each other, which is exactly the state this replaced (three different values across ten files).

| apps/docs/app/gallery/page.tsx | Add a {name, slug, description} entry. Hardcoded, so a new component is invisible in the gallery until it is listed. | | apps/docs/public/r/ | Run pnpm registry:build to rebuild registry artifacts. |

When changing a convention or adding a new rule

Validation

• pnpm --filter @keystoneui/mcp build — confirms MCP changes compile.
• pnpm --filter @keystoneui/docs build (or tsc --noEmit) — confirms docs MDX/routes are valid.
• pnpm registry:build — refreshes apps/docs/public/r/*.json.
• pnpm build:skills — re-tarballs skills/keystoneui-react/ and skills/{others} for keystoneui.io/skills/{name}.tar.gz.

Why this matters

Drift between component source and the skill / AGENTS.md / MCP registry is the single biggest reliability risk for AI consumers. The 6adc8c2 commit is the canonical example: motion/layering tokens were added to AGENTS.md but not to SKILL.md, leaving the skill stale until manual reflow. Treat the agent surface as code — synced together, not as an afterthought.

The eval suite at skills/keystoneui-react/evals/evals.json exists to catch this kind of drift; run it (or extend it) when you change a rule.

Demo File Pattern

Every demo must follow this exact pattern:

"use client";

import { MyComponent } from "@keystoneui/react/my-component";

export default function MyComponentDefault() {
  return <MyComponent>Content</MyComponent>;
}

Demo Registry Pattern

In apps/docs/demos/index.ts:

import MyComponentDefault from "./my-component/default";

// In the demos record:
"my-component-default": { component: MyComponentDefault, file: "my-component/default.tsx" },

MDX Pattern

In apps/docs/content/docs/components/my-component.mdx:

<ComponentPreview name="my-component-default" />

Composition tree

For compound components (≥2 exported parts that nest), insert a ## Composition section after ## Usage with an ASCII tree showing the canonical nesting. Mirrors shadcn/ui's pattern — flows through llms-full.txt automatically since it's plain markdown. Skip for single-piece components (Button, Badge, Input, Spinner, etc.).

## Composition

\`\`\`text
MyComponent
└── MyComponentItem
    ├── MyComponentTrigger
    └── MyComponentContent
\`\`\`

Authoring rules:

• Use box-drawing characters (├──, └──, │) — copy from an existing MDX if unsure.
• Indent two spaces per level.
• Order children top-to-bottom in the order they appear in the canonical default demo.
• Show one branch per repeating part (don't list two MyComponentItems).
• Include conventional non-exported nodes when they appear in the standard demo (e.g. Icon under Alert).

Key File Locations

Component sources

• Component: packages/ui/src/{name}.tsx
• Exports: packages/ui/package.json
• Build entries: packages/ui/tsup.config.ts
• Registry: packages/ui/src/_registry.ts
• Stories: apps/storybook/stories/{name}.stories.tsx
• Demos: apps/docs/demos/{name}/
• Demo registry: apps/docs/demos/index.ts
• MDX docs: apps/docs/content/docs/components/{name}.mdx
• Component nav: apps/docs/content/docs/components/meta.json

AI agent surfaces

• Skill (consumers): skills/keystoneui-react/SKILL.md + mcp.md, cli.md, customization.md, rules/*.md
• Skill evals: skills/keystoneui-react/evals/evals.json
• AGENTS.md (root): /AGENTS.md
• AGENTS.md route: apps/docs/app/agents-md/route.ts
• LLMs.txt routes: apps/docs/app/llms{,-full,-components}.txt/route.ts
• MCP server: packages/keystoneui-mcp/src/{server,tools,fetcher,config}.ts
• MCP docs: apps/docs/content/docs/(getting-started)/agents/{mcp-server,skills,llms-txt,agents-md}.mdx

Project-internal Claude/Cursor skills

• .claude/skills/{component-architecture,design-tokens,popup-patterns,data-table-patterns,contributing}/SKILL.md
• .cursor/rules/*.mdc (symlinks to the same canonical files)