@jamie-tam/forge 6.0.0

package/skills/plan-design-system/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: plan-design-system
+description: "Use when a frontend project needs visual direction (theme, colors, typography, component specs) and DESIGN.md is missing or stale."
+---
+
+# Plan Design System
+
+## Overview
+
+Establish the visual direction for a project's frontend before any implementation begins. This skill produces a `DESIGN.md` file — a plain-markdown design system manifest at project root.
+
+**Core principle:** Establish visual direction before frontend implementation.
+
+**Announce at start:** "I'm using the plan-design-system skill to establish the design system for the frontend."
+
+<HARD-GATE>
+Do NOT proceed to architecture or implementation until the user has approved the design tokens. Visual direction feeds into scaffold, task decomposition, and every frontend task. Without approval, agents will produce unstyled interfaces.
+</HARD-GATE>
+
+## When to Use
+
+- In the v6 prototype-driven flow: **after wireframe lock, before prototype scaffold** (`/greenfield` Step 4.5, `/feature` Step 4.5) — design tokens feed scaffold, every frontend task spec, and the UI/UX review
+- When adding a frontend to an existing backend-only project
+- When the existing `DESIGN.md` is missing or stale
+
+**Not for:**
+- Backend-only projects, CLIs, APIs without a UI
+- Projects where the user provides a complete design system or Figma files (use those directly)
+
+## Prerequisites
+
+1. **Locked concept** — `decks/{name}/slides.md` (concept deck) with approved direction
+2. **Locked wireframe** — `pocs/{name}-wireframe/index.html` (annotated wireframe with the screens this design system must support)
+3. **Knowledge of the target users** — from requirements, the concept deck, or user input
+4. **Check project CLAUDE.md** — if the project declares a CSS framework preference (e.g., `css_framework: "Tailwind + shadcn/ui"`), use that as the starting point instead of asking
+5. **Check for existing `DESIGN.md`** at project root — if one exists, read it first and extend rather than overwrite
+
+If the project has no user-facing UI (backend-only / CLI / library with no frontend surface), skip this skill entirely.
+
+**Backward-compat note:** If invoked in the non-prototype fallback flow (where `plan-brainstorm` ran instead of concept-slides + build-wireframe) and `brainstorm-approved.md` is present, that artifact may also inform token decisions (tech-stack and frontend choices). The prototype-driven inputs above remain the primary source when both are available.
+
+## Skip Check
+
+Before running the procedure, check whether work is actually needed:
+
+- If `DESIGN.md` exists at the project root AND was updated within the current work item (newer than the work item's `created` timestamp in `.forge/work/{type}/{name}/manifest.yaml`), no-op: report "DESIGN.md exists and is current for this work item, no changes needed" and exit. The skill is idempotent.
+- If `DESIGN.md` exists but predates this work item, proceed — Step 1 will treat it as the baseline and extend rather than overwrite.
+- If `DESIGN.md` does not exist, proceed from Step 1.
+
+## The Process
+
+### Step 1: Gather Visual Context
+
+**First, check for an existing `DESIGN.md` at the project root.** If one exists:
+- Read it in full. Treat its tokens as the current baseline.
+- Report to the user: "Found existing DESIGN.md with {theme}, {N} colors, {font-family}. I'll extend it for this feature rather than starting from scratch."
+- Skip to Step 2 with the existing tokens pre-loaded. Only ask the user about tokens not yet defined or tokens that need to change for this feature.
+
+If no `DESIGN.md` exists, ask the user:
+
+1. **Existing design assets?** — Figma files, mockups, screenshots, brand guidelines, design system
+2. **Visual references?** — "Similar to [app/site]", "dark theme like VS Code", "minimal like Linear"
+3. **Framework preference?** — Tailwind, CSS Modules, styled-components, or existing choice from brainstorm
+4. **Theme direction?** — Light, dark, system-adaptive
+5. **Branding constraints?** — Colors, fonts, logos that must be used
+
+If the user provides complete design assets (Figma, detailed mockups), extract the design tokens from them and skip to Step 4.
+
+If the user has no preference, propose a sensible default based on the project type and target users. Offer these aesthetic modes as a starting point:
+
+- **Minimal** — clean, lots of whitespace, restrained color, elegant simplicity
+- **Editorial** — magazine-inspired, strong typography hierarchy, serif accents
+- **Playful** — rounded shapes, vibrant palette, friendly micro-interactions
+- **Corporate** — professional, structured grid, neutral tones, trust-building
+- **Brutalist** — raw, high contrast, monospace, unconventional layout
+- **Dark technical** — IDE-inspired, dark backgrounds, monospace accents, precise
+
+Avoid generic AI-default patterns: Inter/Roboto as body font, safe blue/purple palettes, rounded-everything with no personality. Choose distinctive fonts and committed color palettes that give the project identity.
+
+### Step 2: Define Design Tokens
+
+Produce a design tokens document covering:
+
+#### Color Palette
+
+```yaml
+colors:
+  # Backgrounds (3-level depth scale)
+  bg-primary: "{main background — set the mood}"
+  bg-secondary: "{sidebar, cards — slightly elevated}"
+  bg-tertiary: "{hover states, elevated surfaces}"
+
+  # Text (readable against backgrounds)
+  text-primary: "{high contrast body text}"
+  text-secondary: "{muted text, labels, timestamps}"
+  text-accent: "{links, interactive elements — matches primary}"
+
+  # Semantic (universally understood)
+  success: "{green family}"
+  warning: "{amber family}"
+  error: "{red family}"
+  info: "{blue family}"
+
+  # Interactive (the project's signature color)
+  primary: "{buttons, active states — the brand color}"
+  primary-hover: "{darker/lighter variant for hover}"
+  primary-muted: "{low-opacity variant for tinted backgrounds}"
+```
+
+#### Typography
+
+```yaml
+typography:
+  font-family: "{chosen body font, system-ui fallback}"
+  font-mono: "{chosen monospace font, monospace fallback}"
+  scale:
+    xs: "{~12px — captions, fine print}"
+    sm: "{~14px — secondary text, labels}"
+    base: "{~16px — body text}"
+    lg: "{~18px — subheadings}"
+    xl: "{~20px — headings}"
+    2xl: "{~24px — page titles}"
+  weight:
+    normal: 400
+    medium: 500
+    semibold: 600
+    bold: 700
+```
+
+Recommended alternatives to overused defaults (Inter, Roboto, Arial, Helvetica):
+- **Display/Hero:** Satoshi, Clash Grotesk, Fraunces, Cabinet Grotesk
+- **Body:** Instrument Sans, DM Sans, Geist, Plus Jakarta Sans
+- **Monospace:** JetBrains Mono, Geist Mono, IBM Plex Mono
+
+#### Spacing and Layout
+
+```yaml
+spacing:
+  unit: "4px"            # Base unit (all spacing is multiples)
+  page-padding: "24px"   # Page-level horizontal padding
+  card-padding: "16px"   # Card/panel internal padding
+  gap: "12px"            # Default gap between elements
+  section-gap: "32px"    # Gap between major sections
+
+layout:
+  max-width: "1280px"    # Content max width
+  sidebar-width: "240px" # Sidebar width (if applicable)
+  border-radius: "8px"   # Default border radius
+  border-radius-sm: "4px"
+```
+
+#### Component Conventions
+
+```yaml
+components:
+  buttons:
+    height: "36px"
+    padding: "8px 16px"
+    border-radius: "{from layout tokens}"
+    primary: "solid background in primary color, white text"
+    secondary: "transparent background, border in primary color, primary text"
+    ghost: "transparent background, muted text, subtle hover background"
+
+  inputs:
+    height: "36px"
+    padding: "8px 12px"
+    border: "1px solid subtle border color"
+    focus: "visible ring in primary color"
+
+  cards:
+    background: "secondary background"
+    border: "subtle border (1px, low opacity)"
+    border-radius: "{from layout tokens}"
+    padding: "16px"
+```
+
+#### Motion
+
+```yaml
+motion:
+  approach: "{minimal-functional | intentional | expressive}"
+  duration-fast: "{100-150ms — hover, focus}"
+  duration-normal: "{200-300ms — transitions, reveals}"
+  easing: "{ease-out for entrances, ease-in for exits}"
+```
+
+### Step 3: Define Page Layouts
+
+For each major page/view in the application, sketch the layout structure:
+
+```markdown
+### Home / Dashboard
+- Full-width header with logo + nav
+- Main content area with max-width constraint
+- Card grid for primary content (2-3 columns, responsive)
+
+### Detail View
+- Sidebar (fixed, 240px) with navigation
+- Main content (fluid, scrollable)
+- Optional right panel for metadata
+```
+
+Include responsive breakpoints:
+```yaml
+breakpoints:
+  sm: "640px"    # Mobile landscape
+  md: "768px"    # Tablet
+  lg: "1024px"   # Desktop
+  xl: "1280px"   # Wide desktop
+```
+
+### Step 4: User Review
+
+Present the design tokens document:
+
+> "Visual direction established:
+>
+> 1. **Theme:** {dark/light/adaptive}
+> 2. **Color palette:** {N} colors defined (primary: {color})
+> 3. **Typography:** {font-family}, {N}-step scale
+> 4. **Layout:** {sidebar + main / full-width / etc.}
+> 5. **CSS framework:** {Tailwind / CSS Modules / etc.}
+>
+> This will be installed during scaffold and referenced in every frontend task spec.
+> Please review — changes after implementation are expensive."
+
+Wait for user approval. Adjust if needed.
+
+### Step 5: Write Design Tokens Document
+
+**Output to `DESIGN.md` at the project root.**
+
+- If no `DESIGN.md` exists: create it with the full design tokens document.
+- If an existing `DESIGN.md` was found in Step 1: merge the new/updated tokens into the existing file. Preserve sections that are unchanged. Add new sections for tokens introduced by this feature.
+- **Feature-level overrides:** If this feature introduces tokens that are scoped to this feature only (not project-wide), write those overrides to `.forge/work/{type}/{name}/design-overrides.md`.
+
+### Step 6: Update Feature Manifest
+
+```yaml
+artifacts:
+  design-system:
+    path: DESIGN.md  # project root
+    feature-overrides: design-overrides.md  # only if feature-scoped tokens exist
+    status: approved
+    approved_at: YYYY-MM-DD
+    theme: dark
+    css_framework: tailwind
+    extended_existing: true  # false if created from scratch
+```
+
+## Key Rules
+
+1. **No frontend implementation without visual direction.** If this skill was skipped, agents will produce unstyled UI.
+2. **Design tokens are the source of truth.** Implementation must reference the tokens, not invent colors or spacing.
+3. **User approval is required.** Visual direction is subjective — the user decides, not the agent.
+4. **Keep it practical.** This is not a full design system — it is enough direction for an agent to produce a styled, consistent UI.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Locked concept deck (`decks/{name}/slides.md`) and locked wireframe (`pocs/{name}-wireframe/index.html`) in the prototype-driven flow; or `brainstorm-approved.md` (with confirmed frontend tech stack) in the fallback flow. Plus: requirements (target users), existing `DESIGN.md` (if present — read and extend). |
+| **Produces** | `DESIGN.md` (project root — design tokens, layout specs, component conventions). Optionally `.forge/work/{type}/{name}/design-overrides.md` for feature-scoped tokens. |
+| **Feeds into** | `build-scaffold` (CSS framework install), `plan-task-decompose` (visual specs in tasks), `plan-architecture` (component layout contracts), `quality-uiux` (review against direction) |
+| **Updates manifest** | `artifacts.design-system` |
+
+## Integration
+
+**Called by:**
+- `/greenfield` command at Step 4.5 (after wireframe lock, before prototype scaffold) — skill self-skips when `DESIGN.md` exists and is current for the work item; backend-only / CLI projects without a frontend skip the step entirely via `phase_plan`
+- `/feature` command at Step 4.5 (after wireframe lock, before prototype scaffold) — skill self-skips when `DESIGN.md` is current; backend-only features (API endpoints, schema changes, internal refactors) skip via `phase_plan`
+
+**Pairs with:**
+- `concept-slides` + `build-wireframe` (provide locked concept and wireframe inputs in the prototype-driven flow)
+- `plan-brainstorm` (fallback flow only — provides `brainstorm-approved.md` with confirmed tech stack)
+- `build-scaffold` (reads `DESIGN.md` for CSS framework install and token configuration)
+- `plan-task-decompose` (frontend tasks reference visual specs from `DESIGN.md`)
+- `plan-architecture` (reads `DESIGN.md` for frontend-architecture.md generation)
+- `quality-uiux` (validates implementation against `DESIGN.md` tokens)