interface-design-system

# Interface Design System > Skill by [ara.so](https://ara.so) — Design Skills collection. This skill enables you to build interfaces with systematic consistency using the Interface Design framework. It provides principle-based craft, cross-session memory through `system.md`, and enforcement of design patterns for dashboards, admin panels, and application UIs. ## What This Does Interface Design prevents design drift across sessions by: 1. **Craft** — Applying professional design principles (spacing grids, depth strategies, surface elevation) 2. **Memory** — Persisting decisions in `.interface-design/system.md` that auto-load each session 3. **Consistency** — Ensuring every component follows the same patterns **Key difference:** Without this system, button heights drift (36px, 38px, 40px...). With it, decisions are made once and applied consistently. ## Installation ### Plugin Method (Recommended) ```bash # Add the marketplace /plugin marketplace add Dammyjay93/interface-design # Install via plugin menu /plugin menu # Select 'interface-design' from the menu ``` Restart Claude Code after installation. ### Manual Method ```bash git clone https://github.com/Dammyjay93/interface-design.git cd interface-design cp -r .claude/* ~/.claude/ cp -r .claude-plugin/* ~/.claude-plugin/ ``` Restart Claude Code. ## Core Workflow ### First Session (No system.md) When building UI for the first time: ``` 1. Assess project context (data-heavy dashboard vs. consumer app) 2. Suggest design direction 3. Ask for confirmation 4. State design choices before building each component 5. Build with consistent principles 6. Offer to save system.md ``` **Example:** ``` User: "Build a user dashboard with metrics cards" Agent Response: --- This feels like a data-heavy dashboard — I'd suggest: - Depth: Borders-only (clean, technical) - Surfaces: Subtle elevation shifts (7% → 9% → 11%) - Spacing: 8px base grid - Foundation: Cool tones (slate) Does this direction fit? (y/n) [User: y] Design Tokens: - Depth: borders-only - Surfaces: 7% → 9% → 11% lightness scale - Borders: rgba(255,255,255,0.06) - Spacing: 8px base (8, 16, 24, 32) - Radius: 6px/8px Building dashboard... --- [Builds components consistently] Want me to save these patterns to .interface-design/system.md? (y/n) ``` ### Subsequent Sessions (system.md exists) ``` User: "Add a settings page" Agent Response: --- ✓ Loaded .interface-design/system.md Active System: - Depth: borders-only - Surfaces: 7% → 9% → 11% scale - Spacing: 8px base grid - Borders: rgba(255,255,255,0.06) Building settings page with established patterns... --- ``` ## System File Structure After establishing direction, patterns are saved to `.interface-design/system.md`: ```markdown # Design System ## Direction Personality: Precision & Density Foundation: Cool (slate) Depth: Borders-only ## Tokens ### Spacing Base: 4px Scale: 4, 8, 12, 16, 24, 32, 48 ### Colors --background: hsl(222, 47%, 7%) --foreground: hsl(210, 20%, 98%) --secondary: hsl(215, 16%, 65%) --accent: hsl(217, 91%, 60%) --border: rgba(255,255,255,0.06) ### Surfaces Card: +2% lightness (9%) Panel: +4% lightness (11%) Elevated: +6% lightness (13%) ### Typography Base: 14px Scale: 12, 14, 16, 20, 24 ### Depth Strategy: Borders-only Border: 0.5px solid var(--border) ## Patterns ### Button Primary - Height: 36px - Padding: 12px 16px - Radius: 6px - Font: 14px medium - Usage: Primary actions only ### Card Default - Border: 0.5px solid var(--border) - Padding: 16px - Radius: 8px - Background: var(--card) ### Input Text - Height: 36px - Padding: 8px 12px - Radius: 6px - Border: 0.5px solid var(--border) ``` This file auto-loads at session start. ## Commands ### Initialize Design System ```bash /interface-design:init ``` Starts the design process with principle assessment and direction selection. ### Check Current System ```bash /interface-design:status ``` Displays active design tokens, patterns, and system file location. ### Audit Code Consistency ```bash /interface-design:audit src/components ``` Checks existing code against system.md for inconsistencies: ``` Audit Results: ✓ Button.tsx - matches pattern ✗ Card.tsx - padding 18px (expected 16px) ✗ Input.tsx - height 40px (expected 36px) ``` ### Extract Patterns from Code ```bash /interface-design:extract ``` Scans existing codebase to generate system.md from patterns: ``` Detected Patterns: - Spacing: 8px base (found: 8, 16, 24, 32) - Button height: 36px (5 instances) - Card padding: 16px (3 instances) - Radius: 6px/8px Generate system.md from these patterns? (y/n) ``` ## Design Directions The system infers direction from context, but you can specify: ### Precision & Density ```markdown Personality: Technical, tight spacing Foundation: Cool (slate) Depth: Borders-only Use: Developer tools, admin dashboards ``` ### Warmth & Approachability ```markdown Personality: Generous spacing, soft shadows Foundation: Warm (amber/orange) Depth: Layered shadows Use: Collaborative tools, consumer apps ``` ### Sophistication & Trust ```markdown Personality: Cool tones, refined depth Foundation: Blue-gray Depth: Subtle shadows + borders Use: Finance, enterprise B2B ``` ### Boldness & Clarity ```markdown Personality: High contrast, dramatic space Foundation: Pure grayscale Depth: Strong shadows Use: Modern dashboards, data-heavy ``` ### Utility & Function ```markdown Personality: GitHub-style utility Foundation: Muted grays Depth: Minimal borders Use: Developer tools, technical UIs ``` ## Code Examples ### React Component with System **Button.tsx** (following Precision & Density system): ```tsx // Design checkpoint: // - Height: 36px (from system) // - Padding: 12px 16px (from system) // - Radius: 6px (from system) // - Spacing: 8px base grid interface ButtonProps { variant?: 'primary' | 'secondary'; children: React.ReactNode; } export function Button({ variant = 'primary', children }: ButtonProps) { return ( <button className={` h-9 px-4 rounded-md text-sm font-medium transition-colors ${variant === 'primary' ? 'bg-accent text-white hover:bg-accent/90' : 'border border-border bg-card hover:bg-card/80' } `} > {children} </button> ); } // Tailwind config should use system tokens: // theme: { // extend: { // spacing: { // '4': '16px', // 8px base * 2 // }, // borderRadius: { // 'md': '6px', // } // } // } ``` ### Card Component **Card.tsx**: ```tsx // Design checkpoint: // - Border: 0.5px solid var(--border) // - Padding: 16px (2 * 8px base) // - Radius: 8px // - Surface: +2% lightness elevation interface CardProps { children: React.ReactNode; elevated?: boolean; } export function Card({ children, elevated = false }: CardProps) { return ( <div className={` border border-border rounded-lg p-4 ${elevated ? 'bg-elevated' : 'bg-card'} `} > {children} </div> ); } ``` ### CSS Variables Setup **globals.css**: ```css /* Design system tokens from .interface-design/system.md */ :root { /* Spacing base: 8px */ --spacing-1: 0.25rem; /* 4px */ --spacing-2: 0.5rem; /* 8px */ --spacing-3: 0.75rem; /* 12px */ --spacing-4: 1rem; /* 16px */ --spacing-6: 1.5rem; /* 24px */ --spacing-8: 2rem; /* 32px */ /* Colors - Cool foundation */ --background: hsl(222, 47%, 7%); --foreground: hsl(210, 20%, 98%); --secondary: hsl(215, 16%, 65%); --accent: hsl(217, 91%, 60%); /* Surfaces - Elevation scale */ --card: hsl(222, 47%, 9%); /* +2% */ --panel: hsl(222, 47%, 11%); /* +4% */ --elevated: hsl(222, 47%, 13%); /* +6% */ /* Borders */ --border: rgba(255, 255, 255, 0.06); /* Radius */ --radius-sm: 6px; --radius-md: 8px; --radius-lg: 12px; } ``` ### Dashboard Example **Dashboard.tsx** (full implementation): ```tsx import { Card } from './Card'; import { Button } from './Button'; // Design checkpoint: // - Grid: 24px gap (3 * 8px base) // - Cards: 16px padding (system pattern) // - Metrics: 32px vertical spacing (4 * 8px) export function Dashboard() { return ( <div className="min-h-screen bg-background p-6"> {/* Header */} <header className="mb-8"> <h1 className="text-2xl font-semibold text-foreground"> Dashboard </h1> <p className="text-sm text-secondary mt-2"> Overview of your metrics </p> </header> {/* Metrics Grid - 24px gap */} <div className="grid grid-cols-3 gap-6 mb-8"> <Card> <div className="space-y-2"> <p className="text-sm text-secondary">Total Users</p> <p className="text-2xl font-semibold text-foreground"> 12,549 </p> <p className="text-xs text-accent">+12% from last month</p> </div> </Card> <Card> <div className="space-y-2"> <p className="text-sm text-secondary">Revenue</p> <p className="text-2xl font-semibold text-foreground"> $45,231 </p> <p className="text-xs text-accent">+8% from last month</p> </div> </Card> <Card> <div className="space-y-2"> <p className="text-sm text-secondary">Active Sessions</p> <p className="text-2xl font-semibold text-foreground"> 573 </p> <p className="text-xs text-secondary">Currently online</p> </div> </Card> </div> {/* Data Table */} <Card elevated> <div className="flex items-center justify-between mb-4"> <h2 className="text-lg font-semibold text-foreground"> Recent Activity </h2> <Button variant="secondary">View All</Button> </div> <table className="w-full"> <thead> <tr className="border-b border-border"> <th className="text-left py-3 text-sm text-secondary font-medium"> User </th> <th className="text-left py-3 text-sm text-secondary font-medium"> Action </th> <th className="text-left py-3 text-sm text-secondary font-medium"> Time </th> </tr> </thead> <tbody> <tr className="border-b border-border">