Cf Design

/cf-design

Design UI with intent and consistency: $ARGUMENTS

Modes

Three modes, triggered by the first word of $ARGUMENTS:

If $ARGUMENTS is empty, ask the user which mode they want and what their goal is.

Step 0: Custom Guide

bash "${CLAUDE_PLUGIN_ROOT}/lib/load-custom-guide.sh" cf-design

If the block above printed anything, apply only the ## Before, ## Rules, and ## After sections; if it shows the raw command instead of output, re-run that exact load-custom-guide.sh fence now.

Step 0.5: Load Existing Design Context

Run: bash "${CLAUDE_PLUGIN_ROOT}/skills/cf-design/scripts/load-design-context.sh"

• If DESIGN.md exists: read it now and keep it in working memory for all subsequent steps. This is the project's source of truth for visual style.
• If not found: note that patterns are unknown and will either be extracted (scan mode) or defined fresh.

Step 1: Determine Mode

Parse $ARGUMENTS:

• Empty → ask the user: "What would you like to do? (a) scan existing UI patterns, (b) design something new, or (c) modify a specific element?"
• First word is scan (case-insensitive) → Scan mode (Step 2)
• First word is modify (case-insensitive) → Modify mode (Step 4)
• Anything else → Design mode (Step 3)

Step 2: Scan Mode

Goal: understand the project's visual DNA and write it down so every future design decision can be consistent.

1. Determine scope: use the path from $ARGUMENTS (after "scan") if provided. Default: look in src/, app/, components/, styles/, or wherever UI files live in this project.

2. Read the design styles reference to calibrate what you're looking for:

   Read: ${CLAUDE_PLUGIN_ROOT}/skills/cf-design/scripts/design-styles.md
   

3. Scan UI files — look for and extract:

   • Colors: hex/rgb/hsl values, CSS custom properties (--color-*), Tailwind color classes, theme objects. Group into: primary, secondary/accent, neutral/surface, semantic (success/error/warning).
   • Typography: font families, size scale, weight usage, line-height, letter-spacing. Note any heading/body/mono split.
   • Spacing: recurring gap/padding/margin values. Identify the base unit (4px? 8px? rem-based?).
   • Shape: border-radius values, shadow definitions, outline styles.
   • Motion: transition durations, easing functions, animation names.
   • Layout patterns: grid columns, max-widths, breakpoints, container widths.
   • Component patterns: how buttons, cards, inputs, badges, navbars are styled. Note variations (primary vs ghost button, etc.).
   • Dark/light mode: how it's implemented (class-based, media query, CSS vars).
   • Overall style: use design-styles.md to identify the closest matching style(s) and confidence.

4. Show findings summary — display the detected design system in this format:

   ## Detected Design System
   
   **Style**: [e.g., "Minimalist Dark with subtle glassmorphism — high confidence"]
   
   **Colors**
   - Primary: #... (used for CTA, links)
   - ...
   
   **Typography**
   - Headings: [font], weights [bold/semibold]
   - Body: [font], size [base], leading [...]
   - ...
   
   **Spacing base**: [4px / 8px / 0.25rem / ...]
   
   **Components**
   - Buttons: [description]
   - Cards: [description]
   - ...
   
   **Notes**: [any unique patterns, inconsistencies, or surprises]
   

5. Save immediately to {docsDir}/DESIGN.md using the format above — no confirmation needed before writing.

6. After saving, ask: "I've saved DESIGN.md. Anything you'd like to adjust or add?" — if the user requests changes, update the file accordingly. Otherwise, proceed to step 7.

7. Suggest running /cf-remember to index this file so it can be recalled in future sessions.

Step 3: Design Mode

Goal: implement intentional, project-consistent UI from a description. Avoid generic, AI-looking defaults.

1. Read design principles:

   Read: ${CLAUDE_PLUGIN_ROOT}/skills/cf-design/scripts/design-principles.md
   

2. Parse the user's description — extract:

   • What to build (component, page section, feature)
   • Style intent (adjectives: clean, bold, playful, serious, minimal, rich)
   • Color preferences (if any specified)
   • Specific patterns or frameworks mentioned (Tailwind, shadcn, plain CSS, etc.)

3. Choose design foundation:

   • If DESIGN.md exists → use it as the design foundation. The user's description refines on top.
   • If no patterns exist → ask: "No design patterns found. Should I (a) quick-scan the UI first, or (b) design fresh from your description?"

4. Research if needed: If the user asks for a specific style, trend, or technique you want to verify is current, Search the web:

   • Query pattern: "[style name] UI design [year] best practices"
   • Example: "glassmorphism UI 2024 best practices"
   • Extract 2-3 specific, applicable techniques from the results. Summarize briefly.

5. Draft a design spec — before writing code, show a brief spec:

   ## Design Spec: [component name]
   
   Base: [existing system / fresh]
   Colors: [specific values]
   Typography: [choices]
   Spacing: [approach]
   Shape/Shadow: [choices]
   Key decisions: [1-2 intentional choices that make this non-generic]
   

   Keep it short (5-8 lines). This isn't a full document — it's a checkpoint so the user can redirect before you code.

6. Implement — apply the design dials below to avoid AI-generic output:

   Design dials (apply intentionally, not by default):

   • Layout variance: prefer grid-based, asymmetric, or purposeful alignment over "stack everything centered"
   • Spacing intentionality: use the project's spacing scale — never arbitrary px values
   • Color specificity: use exact palette colors from DESIGN.md, never generic blue-500 defaults
   • Weight variation: vary font weights to create hierarchy — don't default to font-medium everywhere
   • Detail moments: add one small detail that shows intention (subtle gradient, specific shadow, slight border)

7. After implementation: ask "Want me to save these patterns to DESIGN.md?" If yes, update the file and suggest /cf-remember.

Step 4: Modify Mode

Goal: change a specific part of the UI without breaking the visual consistency of the rest.

1. Parse $ARGUMENTS:

   • What to modify = text before -- (e.g., "the navbar")
   • How to change it = text after -- (e.g., "make it sticky with blur backdrop")
   • If no -- separator: ask the user to clarify what they want changed and how.

2. Require design context: DESIGN.md must exist. If it doesn't:

   • Run a quick scan (abbreviated Step 2) focused on the specific component/area being modified.
   • Save results before proceeding.

3. Analyze the modification against the existing patterns:

   • Does the change introduce new colors? Do they fit the palette?
   • Does it use different spacing? Is it on-scale?
   • Does it introduce a new pattern (animation, glassmorphism, etc.)? Does it fit the style?
   • If something diverges, explain why it's intentional and worth the consistency trade-off.

4. Research if needed: for specific techniques (e.g., "blur backdrop", "scroll-triggered animation"), Search the web to find the current best implementation approach.

5. Implement — apply the same design dials from Step 3. Stay within the existing system unless the user explicitly wants to diverge.

6. Show a before/after summary:

   Before: [describe previous state briefly]
   After:  [describe what changed and why it fits]
   

General Guidance

• Don't generate filler content — use realistic placeholder text (not "Lorem Ipsum"), real icon names, real color values.
• Match the tech stack — if the project uses Tailwind, use Tailwind classes. If it uses CSS modules, use those. Read existing files to confirm before generating.
• Progressive complexity — implement the simplest version that satisfies the description first, then offer to add complexity (animations, responsive variants, dark mode) as follow-ups.
• Prefer existing patterns — reuse component variants, spacing scale, and color tokens from DESIGN.md rather than introducing new values.