cf-design

name	cf-design
description	UI design workflow — scan existing UI patterns, design new UI from a description, or modify existing UI while keeping it visually consistent with the rest of the project. Use when the user wants to: design or redesign a component, page, or section; change colors, typography, spacing, or visual style; understand the project's current design system; add new UI that should match existing patterns; or ensure a UI change doesn't look out of place. Use when the user says things like "make it look like", "update the styling", "redesign this", "match the existing style", "what design patterns does this project use", "extract the design system", "add a dark mode", "make it more minimal/bold/clean", or describes a desired visual outcome. Invoke via $cf-design — helps Codex produce intentional, consistent UI.
created	2026-04-30T00:00:00.000Z
updated	2026-07-04T00:00:00.000Z
state	beta

$cf-design

CLI Requirement: NONE — Works without coding-friend-cli. See CLI requirements for the full matrix.

Design UI with intent and consistency: $ARGUMENTS

Modes

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

Invocation	Mode	Purpose
$cf-design scan [path]	Scan	Read existing UI files → extract design patterns → save to docs/DESIGN.md
$cf-design [description]	Design	Implement new UI from the user's description, using existing patterns as a base
$cf-design modify [what] -- [how]	Modify	Change a specific UI element, enforcing consistency with existing patterns

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

---

Step 0: Custom Guide

Custom guide — auto-loaded below (if the raw command shows instead of its output, run it yourself):

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

If output is non-empty, integrate returned sections: ## Before → before first step, ## Rules → apply throughout, ## After → after final step.

Step 0.5: Load Existing Design Context

Run: bash "${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: ${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.

---

Step 3: Design Mode

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

1. Read design principles:

   Read: ${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, use web search:

   • 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)

---

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"), use web search 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.