Kitchen Sink Design System

Build every component for real, wire it into a single sink page, and let the page prove the design system works.

Core Philosophy

• Source of truth — The sink page is the canonical reference for design direction. If it's not in the sink, it doesn't exist.
• No placeholders — Every component rendered on the sink page must be a real, importable module. Never use draft placeholders or TODO stubs.
• Layered semantics — Every component follows a base + variant architecture. Shared structure in the base, visual differences in the variant layer.
• Progressive disclosure — Start with core primitives, layer in app-level components, finish with data display. Each tier builds on the last.
• Design-forward — Define design direction in the sink first; production pages consume what the sink establishes.
• Agent-readable — The design system should be equally consumable by human developers and AI coding agents. Semantic tokens, typed props, and explicit contracts over implicit conventions.
• Framework-native — Respect each framework's idioms. Don't impose React conventions on a Hugo project or vice versa.

Phase 0: Detect Stack

Before anything else, identify the project's framework and lock in the implementation strategy. If you cannot see the file tree, stop and request it.

Detection Signals

Strategy Table

Once detected, lock in these mappings for the rest of the workflow:

Additional Detection Checks

After identifying the framework, also detect:

1. CSS approach — Tailwind (which version?), vanilla CSS, CSS modules, Sass, etc.
2. Icon library — Lucide, Heroicons, inline SVG, icon fonts, Hugo module, etc.
3. Interactivity layer — Alpine.js, HTMX, vanilla JS, React, Vue, Svelte, none.
4. CMS — TinaCMS (tina/), Decap/Netlify CMS (static/admin/), Sanity, Contentful, plain markdown, none.
5. Existing component patterns — Where do components live? What naming conventions are in use? Is there an existing helper like cn()?

Adapt all subsequent phases to what you detected. Do not impose one framework's conventions on another.

Tailwind Detection

Detect which Tailwind version is in use, then read the appropriate source:

• Tailwind v3 — Read tailwind.config.js / tailwind.config.ts for theme.extend (custom colors, spacing, fonts, breakpoints).
• Tailwind v4 — No config file required. Read globals.css, app.css, or the project's main CSS entry for @theme blocks and CSS custom properties (--color-*, --spacing-*, --font-*). Also check for @import "tailwindcss" as a v4 indicator.
• Detection heuristic: If tailwind.config.* exists → v3. If the CSS entry contains @theme or @import "tailwindcss" → v4.
• No Tailwind — Read the project's main CSS for custom properties, Sass variables, or hardcoded values.

Phase 0b: Design System Discovery

Before building anything, determine whether the project already has a documented design system or needs one created from scratch. This phase branches into two modes.

Discovery Manifest

Scan the project root (and common subdirectories like docs/, .github/, .cursor/, .agent/) for any of these files:

Brand & style guides:

• GEMINI.md, CLAUDE.md, AGENTS.md, COPILOT.md
• .cursorrules, .cursor/rules
• .github/copilot-instructions.md
• brand-guide.md, STYLE.md, BRAND.md
• design-tokens.json, tokens.css, tokens.json
• CONTENT_GUIDELINES.md, VOICE.md, BRAND_VOICE.md

Agent configuration files:

• .clinerules, .windsurfrules
• .agent/skills/*/SKILL.md
• README.md (check for design system or brand sections)

Hugo-specific:

• data/design-tokens.json, data/tokens.json
• assets/css/ for custom properties

If any of these contain design direction (colors, typography, voice, component patterns), enter Adopt mode. Otherwise, enter Establish mode.

Adopt Mode — Existing Brand Guide

When the project already has documented design direction:

1. Ingest — Read all discovered guide files. Extract:
   • Color palette (named tokens with hex/HSL values)
   • Typography scale (font families, sizes, weights)
   • Spacing system (if documented)
   • Voice & tone adjectives
   • Component patterns already specified
2. Map — For every extracted token, identify:
   • The corresponding Tailwind config value, CSS custom property, or Hugo data/ entry
   • Whether it's a primitive token (raw color: --blue-500) or semantic token (purpose: --color-interactive)
3. Audit — Scan existing components for drift:
   • Hardcoded hex values instead of tokens
   • Arbitrary Tailwind values (w-[37px]) instead of design scale
   • Inconsistent naming conventions
   • Missing dark mode support
4. Surface gaps — Report what the guide documents vs. what actually exists in code

Establish Mode — No Guide Exists

When the project has no documented design system:

1. Extract — Scan existing CSS/Tailwind for de-facto tokens:
   • Run through globals.css, tailwind.config.*, component files (or Hugo's assets/css/, Astro's src/styles/)
   • Catalog every color, font, and spacing value actually in use
   • Identify the implicit palette and type scale
2. Propose — Generate a design-tokens.md with:
   • Discovered palette organized as primitive → semantic layers
   • Recommended additions to fill gaps (e.g., missing destructive color, no muted variant)
   • Type scale (H1–H6, body, caption) with sizes and weights
   • Spacing ramp mapped to Tailwind's scale (or CSS custom properties for non-Tailwind projects)
3. Voice — Define initial voice & tone:
   • Propose 3–5 voice adjectives based on the project's domain
   • Draft tone map for common UI states
   • Apply the project's franchise placeholder convention (per user rules)
4. Approve — Present the proposal to the user. Do NOT proceed to Phase 1 until tokens and voice are approved.

Automated option: Run bash scripts/scan-components.sh [component_dir] from the skill directory to get a Phase 0 discovery report + EXISTING / MISSING inventory against the tiered checklist.

Reference: design-system-discovery.md

Phase 1: Inventory & Plan

Compare existing components against the tiered checklist. Mark each:

• EXISTING — import from codebase as-is
• MISSING — create the component, then wire it into the sink
• SHORTCODE/MDX CANDIDATE — if a component is meant for content authors (not just the sink), also create the content-author-facing wrapper (shortcode for Hugo, MDX export for React/Astro, etc.)

Tier 1: Core Primitives (mandatory)

• Typography: H1–H6, paragraph, list (ol/ul), inline code, blockquote
• Buttons: primary, secondary, outline, ghost, destructive; sizes sm/md/lg; disabled state
• Badges / Tags: color variants, dismissible
• Avatars: image, initials fallback, sizes, status indicator
• Icons: render a sampler grid from the project's icon library
• Cards: basic, with header/footer, interactive (hover lift)
• Modals / Dialogs: trigger + overlay + close behavior
• Alerts / Toasts: info, success, warning, error variants
• Form controls: text input, textarea, select, checkbox, radio, toggle/switch, with label + error states

Tier 2: Navigation & Layout (include when app-level complexity exists)

• Tabs: horizontal, with active/disabled states
• Breadcrumbs: with separator and current-page indicator
• Sidebar / Nav: collapsible, with active link
• Dropdown menu: trigger + item list + keyboard nav
• Accordion / Collapsible: expand/collapse with animation
• Tooltip / Popover: hover and click triggers
• Navigation patterns: header, sidebar, mobile menu
• Footer variants

Tier 3: Content-Author Components (CMS-dependent)

Include when the site has a CMS or content authors who write markdown/MDX:

• Callout / admonition (info, warning, tip, caution)
• Figure / image with caption
• Button / CTA (link styled as button)
• Embed (YouTube, etc.)
• Card grid (n-up layout of cards from content)

For Hugo, each of these should have both a partial (for templates) and a shortcode (for content authors). For React/Astro, the component serves both roles via MDX.

Tier 4: Data Display (include when data-heavy views exist)

• Table: sortable headers, striped rows, responsive scroll
• Stats / KPI cards: value, label, trend indicator
• Charts: placeholder pattern using the project's chart library (Recharts, Chart.js, etc.)
• Progress bar / Skeleton loaders: determinate and indeterminate states

Phase 2: Layered Component Architecture

Every component — whether EXISTING or newly created — must follow the base + variant pattern. This makes components predictable for both humans and AI agents. The exact mechanism depends on the framework detected in Phase 0.

React / Next.js — CVA Pattern

Use class-variance-authority (CVA) or an equivalent pattern to separate structural base classes from variant-specific classes:

import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils"; // clsx + tailwind-merge wrapper

// ── Base + Variants ──────────────────────────────────────────────
const buttonVariants = cva(
  // Base: shared structure (always applied)
  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        primary:     "bg-primary text-primary-foreground hover:bg-primary/90",
        secondary:   "bg-secondary text-secondary-foreground hover:bg-secondary/80",
        outline:     "border border-input bg-transparent hover:bg-accent",
        ghost:       "hover:bg-accent hover:text-accent-foreground",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
      },
      size: {
        sm: "h-8 px-3 text-sm",
        md: "h-10 px-4 text-sm",
        lg: "h-12 px-6 text-base",
      },
    },
    compoundVariants: [
      { variant: "destructive", size: "lg", class: "font-semibold" },
    ],
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
);

// ── Component ────────────────────────────────────────────────────
interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return (
    <button className={cn(buttonVariants({ variant, size }), className)} {...props} />
  );
}

Hugo — Dict Context Pattern

Hugo components use Go template partials with a dict context contract. Document params in a comment block, use | default for optional params, build BEM classes from variant/size, and delimit to join. Call via {{ partial "components/button" (dict "label" "Submit" "variant" "primary") }}.

Astro — Props Interface Pattern

Astro components define a TypeScript Props interface in frontmatter with defaults via destructuring. Build classes from variant/size, use class:list for merging. Pattern mirrors React CVA but uses Astro's native Props + <slot />.

Static HTML — BEM + Data-Attribute Pattern

Use BEM class conventions (.btn, .btn--primary, .btn--sm) and document the contract in an HTML comment at the top of the file listing available classes and data attributes.

Rules (All Frameworks)

1. Base layer — Shared structural classes: layout, border-radius, font-size, focus ring, transitions, disabled state. These NEVER change between variants.
2. Variant layer — Only what differs: colors, borders, shadows, backgrounds. Defined as named variants.
3. Type / param export — Always export the variant types (React: VariantProps<>, Hugo: param comment block, Astro: Props interface) so consumers (including AI agents) can discover available variants.
4. Escape hatch — Accept an additional class prop and merge it last so consumers can override when necessary.
5. No raw conditionals — Never use isDestructive ? "bg-red-500" : "bg-blue-500" inline. All visual branching goes through the variant API.

Semantic Design Tokens

Components should reference semantic token names, not primitive color names:

The semantic layer means dark mode, theme changes, and brand pivots only require updating the token definitions — component code stays unchanged.

Utility Fallback

If the project lacks a class-merging utility: React — add cn() via clsx + tailwind-merge. Hugo — create a classnames.html partial that filters and delimits a slice. Astro — use built-in class:list. Static — inline concat or a tiny JS helper.

Phase 3: Voice & Tone

Every design system needs content guidance. The sink page includes a Voice & Tone section covering:

• Voice definition — 3–5 adjectives defining the brand's consistent personality. Extract from existing guides or propose based on domain.
• Tone map — How tone adapts to user emotional states (pleased, neutral, confused, frustrated, first-time).
• Content patterns — Standard copy for empty states, error messages, success confirmations, loading states, destructive actions.
• Franchise placeholders — A pop-culture franchise for all placeholder content (form labels, sample data, empty states). Document in the sink header.

Reference: voice-and-tone.md — full templates, examples, and writing checklist.

Phase 3b: Image & Illustration

Photography sourced from the web cannot be used directly (copyright, brand inconsistency). Define an illustration style and a reinterpretation pipeline to transform reference photos into brand-safe assets.

• Define style — Set rendering, palette, detail level, stroke, texture, and mood keywords during discovery. Document in the brand guide.
• Reinterpretation pipeline — Describe subject → strip photographer style → compose prompt with brand tokens → generate → validate against sink samples → optimize & store prompt.
• Sink page section — Include an Illustration Gallery with 3–5 canonical illustrations, a style definition card, and the generation prompt template.
• Rules — Never use unmodified photos. Always store the generation prompt alongside the asset. Every illustration gets descriptive alt text.

Reference: image-reinterpretation.md — full pipeline, prompt templates, validation checklist, and sink page integration code.

Phase 4: Motion & Interaction

Animation is the body language of the product. Define motion patterns in the sink for consistent, purposeful animation.

• Principles — Purposeful (no decorative animation), informative, consistent, respectful of prefers-reduced-motion.
• Duration scale — Define named tokens: --duration-instant (100ms), --duration-fast (200ms), --duration-normal (300ms), --duration-slow (500ms).
• Easing curves — --ease-out for entrances, --ease-in for exits, --ease-in-out for state changes.
• Common patterns — Hover lift, fade in, slide in, expand/collapse, skeleton shimmer, modal entrance/exit.
• Reduced motion — Always include prefers-reduced-motion media query or use Tailwind motion-safe:/motion-reduce: modifiers.
• Sink section — Include an interactive Motion Sampler demonstrating all patterns with their duration/easing tokens displayed.

Reference: motion-guidelines.md — full CSS/Tailwind code, keyframe definitions, Framer Motion patterns, and reduced-motion implementation.

Phase 5: Build Components

For every MISSING item from Phase 1, create the component using the framework's native patterns.

File Location & Naming

Component Creation Standard (All Frameworks)

1. Create the component in the project's established component location with a stable export/interface.
2. Document the interface at the top of the file:
   • React: TypeScript interface or JSDoc props comment.
   • Hugo: Go template comment block listing expected dict keys, their types, and defaults.
   • Astro: TypeScript Props interface in frontmatter.
   • Static: Comment block describing expected classes/data attributes.
3. Use design tokens from the project's Tailwind config, CSS custom properties, or Hugo data/ entries; avoid arbitrary/magic values.
4. Keep components self-contained — rely only on dependencies already in the project.
5. Make interactive components actually interactive using whatever the project's interactivity layer is:
   • React: useState, event handlers
   • Hugo: Alpine.js x-data or <details>/<summary> for zero-JS
   • Astro: client:load + framework islands
   • Static: vanilla JS, Alpine.js, or <details>/<summary>
6. Apply the variant pattern from Phase 2 (CVA for React, dict params for Hugo, Props for Astro).
7. Apply voice & tone patterns from Phase 3. Error messages answer what/why/fix. Empty states guide the user.
8. Apply motion patterns from Phase 4. Use the defined duration and easing tokens.
9. Wire the component into the sink page immediately. No placeholders.

Content-Author Wrappers

When a component is marked as a SHORTCODE/MDX CANDIDATE in Phase 1:

• Hugo — Create a shortcode in themes/<theme>/layouts/shortcodes/ that wraps the partial. Pass through all relevant parameters.
• React / Astro — The component itself is usable in MDX. Ensure it's exported from the project's MDX component registry.
• Static — Document usage instructions for copy/paste inclusion.

Phase 6: Assemble Sink Page

Create the sink route file based on the framework detected in Phase 0.

Sink Route Creation

React / Next.js — app/sink/page.tsx

• Add "use client" directive.
• Return null when process.env.NEXT_PUBLIC_VERCEL_ENV === "production".
• Use examples/minimal-sink.tsx as a starter template.

Hugo — content/sink/_index.md + layouts/sink/list.html

• Frontmatter: type: sink, exclude from sitemap (sitemap: exclude), hide from nav.
• Layout: check hugo.Environment or site.Params.showSink; redirect in production.
• Preferred production guard: config overlay at config/production/hugo.toml with showSink = false.
• Use examples/minimal-sink.html as a starter template.

Astro — src/pages/sink.astro

• Check import.meta.env.PROD and return redirect or empty page.

SvelteKit — src/routes/sink/+page.svelte

• Use $app/environment to check for production.

Nuxt — pages/sink.vue

• Use useRuntimeConfig() to check environment.

Static HTML — sink.html

• Simply don't include in production deployment.

Architecture Rules

• Never import other page/route files — only import components or define helpers locally.
• The sink page is a dev tool — exclude it from production, sitemap, RSS, search indexes, and navigation.

Sink Page Layout

The sink page follows the same section structure regardless of framework. Adapt the syntax to match.

Sections (in order):

1. Header — Title, description, last-updated timestamp, franchise declaration
2. Design Tokens — Color palette (primitive → semantic), typography scale, spacing ramp
3. Voice & Tone — Voice definition, tone map, content pattern examples
4. Illustration Gallery — Canonical illustrations, reinterpretation examples, prompt template
5. Site Header — Rendered inline to test responsive breakpoints and nav states
6. Site Footer — Rendered inline to test link columns and brand consistency
7. Typography — H1–H6, body, caption, lists, blockquote, inline code
8. Buttons — All variants × sizes × states (variant grid)
9. Badges — Color variants, dismissible
10. Cards — Basic, with header/footer, interactive
11. Form Controls — All input types with label + error states
12. Modals & Dialogs — Working open/close demo
13. Alerts — All severity variants
14. Motion Sampler — Interactive demos of hover lift, fade, slide, expand/collapse
15. Content-Author Specimens — How shortcodes/MDX components render (if applicable)
16. Tier 2 components — Tabs, breadcrumbs, accordion, tooltip, dropdown (if applicable)
17. Tier 4 components — Table, stats cards, progress, skeleton (if applicable)
18. Chaos Laboratory — Token visualization, state matrix, dark/light side-by-side

Chaos Laboratory

1. Token visualization — Programmatically render design tokens (colors, spacing).
   • React: Import resolved config via resolveConfig.
   • Hugo: Export tokens to data/design-tokens.json at build time, read with site.Data.
   • Astro: Import config in frontmatter.
   • Static: Maintain a JSON file manually or generate with a script.
2. State matrix — Render variants side by side (default, hover, focus, disabled, active).
3. Theme test — Light and dark columns, forced via wrapper class.
4. Responsive stubs — iframe containers with fixed widths (320px, 768px) to verify mobile layouts.

Phase 7: Verify

Run these checks before considering the sink complete. Commands vary by framework.

Automated Checks

Optional accessibility audit: pnpm dlx @axe-core/cli http://localhost:<port>/sink

Manual Checklist

• A. Completeness — Every Tier 1 item is present. Tier 2/3/4 items included where relevant.
• B. Real components — Every rendered element is imported from the project's component location (no inline-only markup pretending to be a component).
• C. Layered architecture — Every component uses the framework-appropriate variant pattern (CVA for React, dict params for Hugo, Props for Astro, BEM for static).
• D. Semantic tokens — No hardcoded hex values or primitive color names in component code.
• E. Interactivity — Modals open, toggles toggle, tabs switch, dropdowns expand. Every stateful component works.
• F. Voice & tone — Content patterns documented. Error messages answer what/why/fix. Empty states guide the user.
• G. Motion — Animations use defined duration/easing tokens. prefers-reduced-motion respected.
• H. Theming — Dark/light columns render correctly. No hard-coded colors bypassing tokens.
• I. Production guard — Sink page is excluded from production via the framework's native mechanism.
• J. No import cycles — Sink page does not import any page/route file.
• K. Content-author wrappers — Shortcodes/MDX exports pass through all relevant parameters (if applicable).

CMS Notes

The sink page is never CMS-managed — it's a developer tool.

However, when a CMS is present, content-author-facing components (Tier 3) should respect the CMS content model:

• TinaCMS — Component params should align with the fields defined in tina/config.ts collections. Note: TinaCMS visual editing requires React — in Hugo projects, Tina functions only as a markdown/frontmatter editor GUI.
• Decap CMS — Component params should map to widget types in static/admin/config.yml.
• MDX-based CMS (Contentful, Sanity, etc.) — Exported components should match the expected props shape from the CMS schema.

AI Agent Readiness

Ensure the design system is consumable by AI agents: use semantic tokens over primitives, store tokens in CSS custom properties and/or JSON, export typed props as the API contract, use purpose-based naming (text-muted-foreground not gray-light), reference tokens in the project's rules file (CLAUDE.md, .cursorrules, etc.), and treat the sink page as the single source of truth.

Companion Skills

When available, leverage: design-lookup for CSS components, SVG icons, and design inspiration during Establish mode. Frontend/brand identity skills for project-specific visual identity constraints during discovery. deep-research for evaluating design system approaches from scratch. This skill acts as the integrator — consuming companion skill outputs and codifying them into the component library and sink page.

Anti-patterns

• Draft placeholders — {/* TODO: add button */} is never acceptable. Build the real component.
• Arbitrary Tailwind values — w-[35px] or text-[#ff0000] instead of using config tokens.
• Raw conditional classes — isDestructive ? "bg-red-500" : "bg-blue-500" instead of using variants.
• Importing page files — import X from "../other-page/page" creates coupling and build issues.
• Skipping tiers — Don't jump to Tier 4 charts before Tier 1 buttons exist.
• Static mockups — A modal that doesn't open, a toggle that doesn't toggle, a tab bar that doesn't switch.
• One-off inline components — If it's rendered in the sink, it belongs in the component directory as an importable module.
• Appearance-based token names — blue-primary instead of color-interactive. Semantic names survive brand pivots.
• Missing voice guidance — A sink without content patterns is only half a design system.
• Decorative animation — Motion without purpose. Every animation should inform or guide.
• Framework mismatch — Imposing React idioms (JSX, hooks) on a Hugo or static HTML project.

Reference

For detailed per-component specs (expected props, variants, states, accessibility), the sink page section template, and concrete code examples:

• Components: component-catalog.md
• Discovery: design-system-discovery.md
• Voice & Tone: voice-and-tone.md
• Image & Illustration: image-reinterpretation.md
• Motion: motion-guidelines.md