tools-ui-frontend-design

Frontend Design

Build distinctive UI that is both creatively intentional and design-system-compliant.

This skill bridges the Claude frontend-design plugin's creative philosophy with this repo's concrete design token system, brand language, and component library. The plugin provides the "think boldly" mindset; this skill constrains it to the actual design system.

Philosophy (from the Claude frontend-design plugin)

• Commit to a BOLD aesthetic direction before coding
• Avoid generic AI aesthetics (purple gradients, Inter/​Roboto, predictable grid layouts)
• Every design choice should be intentional and defensible
• High-impact micro-interactions and motion where they serve the user
• Atmosphere and depth through composition, not through arbitrary values

Constraints (this repo's design system)

ALL design work MUST use the repo's token system. The tokens and brand dossier define the creative canvas — boldness comes from HOW you compose them, not from bypassing them.

Mandatory References

Load these before any design work:

Hard Rules

1. ALL colors via semantic tokens (bg-primary, text-fg, bg-accent, etc.) — never arbitrary hex
2. ALL typography via font tokens (font-sans, font-heading, font-mono) — never import external fonts
3. ALL spacing via 8-pt rhythm (p-4, gap-6, space-y-4) — never arbitrary px
4. ALL radius via token scale (rounded-md, rounded-lg) — never arbitrary
5. ALL shadows via token scale (shadow-sm, shadow-md, shadow-lg)
6. Use cn() from @acme/​design-system/​utils/​style for class merging
7. Use existing @acme/​design-system components before creating new ones
8. Mobile-first responsive: base → md: (768px) → lg: (1024px) → xl: (1280px)

Where Boldness Lives

The plugin's creative philosophy applies to:

• Composition: How you arrange components, use whitespace, create visual hierarchy — asymmetry, overlap, and diagonal flow are encouraged through layout choices (grid-cols, order, absolute positioning), not through arbitrary spacing values
• Motion: CSS transitions/​animations on existing token values (opacity, transform, scale) — use transition-* utilities and @keyframes with token-derived values
• Density context: Choose .context-operations / .context-consumer / .context-hospitality intentionally — this changes the entire feel without breaking the system
• Brand expression: Each business has a distinct brand dossier — lean into its personality, voice, and visual identity. The dossier IS the aesthetic direction
• Component selection: Choose the right atom/​molecule from the design system, don't default to the obvious choice. A StatCard grid tells a different story than a DataGrid table
• Surface layering: Use surface-1, surface-2, surface-3 to create depth and hierarchy — this is how the design system provides atmosphere

The plugin's creative philosophy does NOT override:

• Color values (use tokens)
• Font choices (use tokens)
• Spacing values (use 8-pt rhythm)
• Border radius (use token scale)
• Creating custom CSS properties outside the design system

Workflow

Step 1: Resolve the Business

Read docs/​business-os/​strategy/​businesses.json to find the target business for the work.

Load the brand dossier: docs/​business-os/​strategy/<BIZ>/​brand-dossier.user.md

If no brand dossier exists (common for PLAT, BOS, PIPE, XA): use base theme tokens directly from packages/​themes/​base/​src/​tokens.ts as the design reference. No redirection needed — the design system tokens provide a complete and correct palette. Reserve /​lp-assessment-bootstrap <BIZ> for operating businesses that will have a distinct brand identity.

Step 2: Load Design System Context

1. Read .claude/​skills/​lp-design-system/​SKILL.md for the token quick-reference
2. Read packages/​themes/<theme>/​src/​tokens.ts for the business's concrete token values
3. Read docs/​design-system-handbook.md for available components
4. If the feature is complex, also read docs/​typography-and-color.md

Step 3: Design Direction

With the brand dossier and tokens loaded, establish a creative direction:

• What density context fits? (operations for dashboards, consumer for marketing, hospitality for booking)
• What surface layering creates the right depth? (flat vs elevated vs deeply layered)
• What motion principles serve the user? (subtle transitions vs dramatic reveals)
• How does the brand personality translate to composition choices?

Step 4: Build

Implement using:

• @acme/​design-system components (atoms, molecules, primitives)
• Semantic Tailwind tokens (never arbitrary values)
• cn() for conditional class merging
• Proper TypeScript types for all props

Step 5: Verify

After building, run /​lp-design-qa to audit:

• Token compliance (no arbitrary values)
• Brand dossier alignment
• Accessibility (contrast ratios, keyboard navigation, ARIA)
• Responsive behavior across breakpoints

Step 6: Document (optional)

For significant features that benefit from visual documentation, suggest /​lp-visual to create diagrams showing the component architecture, state flows, or interaction patterns.

Anti-Patterns