Author a new Storefront Next design-system component the right way — pick the correct layer (primitive vs composite), reuse-or-extend before creating, define CVA variants bound to semantic tokens, add data-slot attributes, satisfy the accessibility checklist, and ship a Storybook story. Use when asked to create, add, or build a new UI component, button/badge/tile/card variant, or design-system primitive. This is the design-system authoring discipline; for createPage/Suspense/shadcn page-rendering patterns see sfnext-components.
Author a new Storefront Next design-system component the right way — pick the correct layer (primitive vs composite), reuse-or-extend before creating, define CVA variants bound to semantic tokens, add data-slot attributes, satisfy the accessibility checklist, and ship a Storybook story. Use when asked to create, add, or build a new UI component, button/badge/tile/card variant, or design-system primitive. This is the design-system authoring discipline; for createPage/Suspense/shadcn page-rendering patterns see sfnext-components.
Create a Component Skill
This skill is the authoring discipline for adding a new component to a Storefront Next storefront: choosing the right layer, reusing before creating, and meeting the token / a11y / Storybook requirements that keep the design system consistent.
It complements sfnext-components. That skill covers engineering patterns — createPage, Suspense/Await streaming, shadcn/ui setup, the cn() utility. This skill covers design-system authoring — the layer model, the extend-before-create gate, CVA variants bound to semantic tokens, data-slot, accessibility, and story coverage. Use both together when building UI.
Before you start — scan first (extend before create)
Do not create a new component file until you have run this scan:
Search src/components/ for components with a similar name or behaviour.
Search src/components/ui/ for Shadcn primitives — run npx shadcn@latest add <name> to check whether it exists before hand-rolling one.
Apply the REUSE / EXTEND / CREATE decision:
REUSE — an existing component already does this → use it as-is.
EXTEND — an existing component is close → add a new CVA variant (cheaper than a new file).
CREATE — nothing exists → proceed with this skill.
Token rules: every class that affects color MUST use a semantic token utility (bg-primary, text-foreground, border-border, …). No raw hex, no bg-black, no text-gray-500. See Token System Reference.
