design-system

Files (7)

• SKILL.md
• figma-workflow.md · reference/
• output-template.md · reference/
• pencil-workflow.md · reference/
• platform-guide.md · reference/
• primitives.md · reference/
• semantic-tokens.md · reference/

SKILL.md (first lines)

# Design System

> **IMPORTANT:** Dispatcher only. Load reference files on demand. See routing table below.

## Philosophy

- **Understand → Plan → Approve → Build** — first understand WHAT you're designing (web? app? document?), then propose visuals, get approval, then build. Never skip steps
- **Collections → Components → Screens** — organize variables into collections, build components from those variables, assemble screens from component instances. Never skip layers
- **Iterate, never rebuild** — when the user requests a change, modify only what changed. Never delete existing work to start over
- **Modes are first-class** — light/dark, brand variants are not afterthoughts. Design for modes from day one
- **Semantic over literal** — name tokens by purpose (`color-primary`), not value (`blue-500`)
- **Components are configurable, not duplicated** — properties and variants, not 20 separate components

## Workflow

### 0. Understand the Deliverable (MANDATORY)

**Gate:** Before proposing visuals, understand WHAT you're designing.

Ask (in Spanish): "Que tipo de producto es? Pagina web estatica? App web? App movil? Landing page? Dashboard? Documento?"

This determines layout patterns, navigation, density, and component needs. A web portfolio is NOT a PDF resume. A dashboard is NOT a landing page.

#### Platform Detection

Read the PRD's **Scope → Platform** field. If missing, ask: "Para qué plataforma? Web, mobile, o ambos?"

- `web` → standard web tokens
- `mobile` → load `reference/platform-guide.md`. Use iOS/Android type scales, touch targets (44pt+), platform-native font sizes
- `both` → load `reference/platform-guide.md`. Generate BOTH web and mobile token sets. Document the mapping (abstract → web CSS → iOS Swift → Android Compose) as shown in the platform guide

### 1. Research & Inspiration (MANDATORY)

**Gate:** Before proposing visuals, research what works in the domain. Never design from scratch.

1. **Inspiration sites** — search for references on:
   - **Dribbble** / **Behance** — UI components and full case studies
   - **Awwwards** — award-winning web design
   - **Mobbin** / **Screenlane** — real mobile app patterns (essential if platform is `mobile` or `both`)
   - **Collectui** / **Landbook** — categorized UI inspiration
2. **Domain-specific search** — search "{project domain} UI design" (e.g., "healthcare SaaS dashboard design", "B2B workflow app mobile"). Find 3-5 real products in the same domain
3. **Font research** — search Google Fonts for fonts matching the project tone. Propose 2-3 pairings (heading + body). Consider:
   - Readability at small sizes (critical for mobile)
   - Variable font availability (better performance)
   - Language support (if i18n is needed)
   - If platform is `both`: verify the font works on web AND has a good mobile equivalent (or use the same)
4. **Color palette research** — search palette tools (Coolors, ColorHunt, Realtime Colors) for palettes matching the domain

Document all findings — they feed into the visual proposal.

### 1.5. Present Visual Proposal (MANDATORY)

**Gate:** Before ANY canvas work, present a proposal and get explicit approval.

Include:
- **References found** (3-5 links with what you liked about each)
- **Color direction** (2-3 options matching the domain context, with full scale preview 50→950)
- **Typography** (specific Google Fonts with links, not just "sans-serif". Show the pairing rationale)
- **Tone** (density, corners, mood, reference site)
- **Layout** (structure, navigation, mobile approach)
- **Modes** — if user wants dark+light, show both in the proposal
- **Platform considerations** — if `both`, explain how web and mobile layouts will differ

Format in Spanish. Wait for explicit approval. Iterate if needed.

### 2. Check Existing System

Read `<docs>/01-project/design-system.md`. If exists → skip to step 7.

### 3. Create Variable Collections

See `reference/primitives.md` for complete scales. See `reference/semantic-tokens.md` for mapping.

**Collection 1: Primitives** — raw values, no semantic meaning, never consumed directly
**Collection 2: Semantic** (with modes) — purpose-based names that alias primitives, values change per mode
**Collection 3: Component** (optional) — scoped to specific UI elements

#### Color Scale (MANDATORY — full 11-step ramp)

Every hue family MUST have the complete scale: **50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950**. This applies to:
- **Brand primary** — the main brand color ramp
- **Brand secondary** — if the project uses a secondary color
- **Neutral/Gray** — the gray family chosen for the project
- **Status colors** — red (danger), amber (warning), green (success), blue (info)

Never define just "primary color" as a single hex. The full ramp is required for hover states, subtle backgrounds, borders, dark mode mapping, and accessible contrast.

#### Font Selection (MANDATORY — specific font, not system stack)

Choose a specific font from **Google Fonts** (or the project's brand font if provided). The system font stack is a fallback, not a choice.

1. Select 2-3 font candidates based on the research from Step 1
2. Define the full weight set used: 300 (light), 400 (normal), 500 (medium), 600 (semibold), 700 (bold)
3. Define the full type scale: **display, 3xl, 2xl, xl, lg, base, sm, xs** — with pixel values from `reference/primitives.md`
4. If platform is `both`: define web sizes (px/rem) AND mobile sizes (pt for iOS, sp for Android) using `reference/platform-guide.md`

#### Platform-Specific Tokens

If the PRD `Platform` is `mobile` or `both`:
- Load `reference/platform-guide.md`
- Add mobile-specific tokens: touch target minimums (44pt iOS, 48dp Android), safe area awareness, platform font sizes
- Document the abstract → platform mapping table

Tool-specific implementation: load `reference/pencil-workflow.md` or `reference/figma-workflow.md`.

### 4. Build Component Library (MANDATORY)

**Gate:** Components MUST exist BEFORE any screen design.

Each component needs: **properties** (boolean, text, instance swap), **variants** (state, size, type), and **all values from variables**.

#### Library Structure

Split into **2 separate frames** positioned to the RIGHT of screens:

**Frame 1: "Design Tokens"** — visual reference, not reusable components. Uses columns.

```
Design Tokens

From ernesto2108/forge, MIT.

More from ernesto2108/forge