name: ui user-invocable: false description: UI implementation — TailwindCSS v4, Radix UI primitives, accessibility, Storybook, i18n, diagrams. Implements the direction set by the design skill. Use for theming, component composition, accessibility compliance, stories, internationalization, or creating diagrams. version: "1.4.1" design_token_version: "2.3.0" status: active packages: ["shared", "client", "admin"] dependencies: ["design"] last_updated: "2026-04-17" last_verified: "2026-04-17" changelog:

• "1.4.1 — Added 10-step New Component Runbook (single golden path replacing scattered steps). Part 3 Dialogs now names DialogShell (shared, default) and AdminDialog (admin, strict M3) with file paths. Admin Cockpit Mode trimmed to ui-implementation specifics, pointing back to design/SKILL.md § Admin Cockpit Carve-Out as canonical. Registry design_token_version synced to 2.3.0 (was drifted at 2.2.0). Spring motion tokens now real in theme.css."
• "1.4.0 — Added view-transitions.md (inherited from former design/implementation.md — execution details belong here, not in design). design_token_version pinned to design skill 2.3.0. Material tokens (--color-material-, --blur-material-) now implemented in theme.css; compliance guidance should reference them over hardcoded glass values."
• "1.3.0 — Part 1 replaced with pointer to design skill. Design Thinking and Green Goods Aesthetic Tokens moved wholly to design/language.md and root DESIGN.md to eliminate duplication."

UI Skill

Unified UI development guide: design thinking, component development, TailwindCSS v4, Radix UI, accessibility, Storybook, i18n, and diagrams.

Activation

When invoked:

• Choose a clear aesthetic direction before writing code.
• Preserve existing Green Goods design tokens when working in existing views/components.
• Pair design work with compliance checks (accessibility + responsive).
• All shared components need Storybook stories.
• Dedicated Storybook authoring now routes through this skill. Do not use a separate storybook agent.

Part 1: Design Direction Pointer

Design direction, paradigm selection, spatial patterns, material language, and aesthetic tokens are owned by the design skill.

• Warm Earth language (shape, motion, color, material behavior, hero moments) — .claude/skills/design/language.md
• Role hierarchy (canvas / ink / stone / green-as-tertiary-accent) — root DESIGN.md + design/language.md § Color Direction
• Paradigm selection (Command / Ambient / Data Landscape / Conversational / Ritual) — design/SKILL.md
• AI prompt vocabulary for admin cockpit — design/prompt-contract.md

Execution-level tokens live in packages/shared/src/styles/theme.css, packages/client/src/styles/typography.css, and packages/client/src/styles/animation.css. This skill focuses on how to express the direction in code — Tailwind, Radix, Storybook, compliance, i18n.

Admin Cockpit Mode

The design identity (restrained operator cockpit, why-it's-different-from-client, vocabulary, never-use list) is canonical in design/SKILL.md § Admin Cockpit Carve-Out and design/prompt-contract.md. Read those first.

UI-level implementation rules that follow from that identity:

• Layout default: PageHeader → one primary workspace → optional secondary context in a sheet or rail. Start from layout and flow before reaching for Card.
• Card usage: cards and elevated surfaces are for records or bounded interactions, not the default page structure. Prefer one dominant workspace surface per route. Avoid nested stacks of rounded bordered panels.
• Tokens: shared semantic tokens + one workspace accent. No decorative gradients behind routine product UI.
• Reference composition: admin /hub route is the canonical cockpit layout — model new admin surfaces on it.
• Dialogs: use DialogShell from @green-goods/shared by default; reserve AdminDialog for strict M3 flows (see Part 3).

Part 2: Component Development Workflow

1. Check existing patterns (CanvasLayout, AccountSurface, RightSheet, PageHeader, ListToolbar, SortSelect, Surface, Card, Alert, FormField)
2. Develop reusable components in Storybook first (bun run storybook in packages/shared)
3. Follow Radix UI + tailwind-variants patterns (see radix-ui.md)
4. Run compliance checklist before integration (see compliance.md)
5. Test light/dark mode via Storybook toolbar
6. Verify admin routes in a real browser for desktop and mobile when changing page-level composition
7. Add i18n for all user-facing strings (see i18n.md)

New Component Runbook

Linear golden path from blank file to merge-ready. Collapses the rules otherwise scattered across the design + ui skills into one pass.

Admin-specific shortcut: steps 1-4 are usually pre-answered — admin = Command Surface + solid material + M3 shapes + Standard motion. Start at step 5.

Client-specific shortcut: hero-moment components (garden creation, hypercert mint, …) override step 4 to Expressive motion and step 2 to dramatic material. See design/language.md § Hero Moments.

Part 3: Implementation Patterns

All UI patterns use Radix UI primitives + tailwind-variants (tv()). See radix-ui.md for Dialog, Select, Popover composition examples.

• Dialogs: two project wrappers sit on top of Radix Dialog.*:
  • DialogShell — default. packages/shared/src/components/Dialog/ConfirmDialog.tsx, exported from @green-goods/shared. Props: open, onOpenChange, title, description?, icon?, size (md|lg|xl|2xl), children, preventClose?. Mobile bottom-sheet + desktop centered, glass-floating, handles z-overlay/z-modal. Use for all new dialogs in client and admin unless strict M3 anatomy is required.
  • AdminDialog — admin-only, strict M3. packages/admin/src/components/AdminDialog.tsx. Props: open, onOpenChange, title, description?, icon?, children, actions?. Uses --m3-shape-xl, --m3-surface-container-high, --m3-elevation-3, 32% scrim. Reserve for flows that need the M3 actions slot and elevation-3 centered layout (CookieJar modals remain on this wrapper).
  • Raw Radix Dialog.* namespace only when neither wrapper fits — see radix-ui.md for composition rules.
• StatusBadge: tv() with status variants (active, pending, failed, offline) mapping to semantic colors with dark mode
• Cards: Compound pattern (Card, Card.Header, Card.Body, Card.Footer) with tv() variants for interactive and elevated -- used for GardenCard, WorkCard, ActionCard
• Animations: CSS animations (transform, opacity) via animate-in/fade-in/slide-in utilities. Staggered reveals with animationDelay for list items. Skeletons with animate-pulse.
• Responsive layouts: Mobile-first (flex-col -> sm:flex-row), auto-fill grids with minmax()

Reference Files

Anti-Patterns

Design

1. Shipping generic default UI without an explicit visual direction
2. Ignoring existing design tokens in established Green Goods surfaces
3. Prioritizing novelty over accessibility, readability, and interaction clarity
4. Using placeholder motion without intent (random micro-animations)
5. Creating visual complexity without corresponding information hierarchy

TailwindCSS

1. Using tailwind.config.js instead of CSS-first v4 configuration
2. Using raw color values (bg-green-500) instead of semantic tokens (bg-primary)
3. Defining theme tokens in app packages instead of packages/shared/src/styles/theme.css
4. Skipping dark mode values for new color tokens
5. Using prefers-color-scheme instead of [data-theme] attribute

Radix UI

1. Using @radix-ui/themes instead of primitives + TailwindCSS
2. Skipping Dialog.Title (required for accessibility -- use sr-only to visually hide)
3. Destructuring Radix imports instead of namespace imports (Dialog.Root, not Root)

Accessibility & Compliance

1. Relying on color alone to convey state or validation failures
2. Shipping forms without accessible labels and error associations (aria-describedby)
3. Ignoring prefers-reduced-motion for animated interactions
4. Assuming desktop-only layouts without mobile verification

i18n

1. Hardcoding user-facing strings instead of intl.formatMessage() / FormattedMessage
2. Forgetting to update all three language files (en.json, es.json, pt.json)
3. Using physical CSS properties (margin-left) instead of logical (margin-inline-start) for RTL

Storybook

1. Skipping tags: ["autodocs"] on component stories
2. Hardcoding data in stories instead of using mock factories from test-utils
3. Skipping loading/error/empty state stories

Decision Tree

What kind of UI work?
|
+--> Design direction / visual identity?
|    --> design skill (language.md, SKILL.md, prompt-contract.md)
|    --> root DESIGN.md for role hierarchy and atmosphere
|
+--> New component?
|    --> Part 2 (Component Development Workflow)
|    --> radix-ui.md for primitives
|    --> storybook.md for story co-location
|    --> compliance.md before merge
|
+--> Theme / token / dark mode change?
|    --> tailwindcss.md (Parts 2-3)
|
+--> Accessibility audit?
|    --> compliance.md (Parts 1-2)
|    --> storybook-addons.md (a11y addon)
|
+--> Responsive layout issue?
|    --> compliance.md (Parts 3, 10)
|    --> tailwindcss.md (Part 4)
|
+--> Storybook story or visual regression?
|    --> storybook.md (writing stories)
|    --> storybook-testing.md (visual regression, Chromatic)
|    --> storybook-addons.md (addon config, design system docs)
|
+--> Translation / i18n?
|    --> i18n.md (react-intl + Browser Translation API)
|    --> compliance.md Part 6 (i18n checklist)
|
+--> Architecture / flow diagram?
|    --> mermaid.md (diagram type selection)
|
+--> Animation / motion?
|    --> This file, Part 3 (Implementation Patterns)
|    --> compliance.md Part 4 (reduced motion)

Related Skills

• react -- Component composition, state management, React 19 APIs, performance optimization
• testing -- TDD workflow, Vitest patterns, React Testing Library
• data-layer -- Offline-first patterns, IndexedDB, sync state that integrates with UI
• react (error-handling sub-file) -- Toast service, mutation error handlers, user-facing error messages
• react (performance sub-file) -- Bundle budgets, re-render optimization, virtualization