lp-design-spec

# Design Spec

Produce a design specification that maps a feature requirement to concrete design-system components, semantic tokens, and layout decisions — grounded in the business's brand language. Feeds directly into `/lp-do-plan` to raise confidence on UI tasks.

## Operating Mode

**ALLOWED:** Read codebase, read docs, read theme tokens, create/update design spec docs, create/update brand language docs.
**NOT ALLOWED:** Write application code, modify components, change tokens, run builds. Design only — implementation is `/lp-do-build`'s job.

## When to Use

- New page, section, or significant UI component
- Visual refresh or rebrand work
- Any feature where fact-find flags `Design-Spec-Required: yes`
- When `/lp-do-plan` produces low-confidence UI tasks (design decisions unmade)
- Standalone brand language bootstrapping for a new business

## Invocation

### Fast Path

```
/lp-design-spec <feature-slug>
```

Expects `docs/plans/<feature-slug>-fact-find.md` to exist. Reads it, resolves the business unit, loads brand language, and begins spec creation.

### Discovery Path

```
/lp-design-spec
```

No argument — presents the app-to-business mapping and asks what you're designing for.

### Brand Bootstrap Mode

```
/lp-design-spec --bootstrap <BIZ-CODE>
```

Runs GATE-BD-07 pre-flight for the business unit without producing a feature design spec. Blocks and redirects to `/lp-assessment-bootstrap <BIZ>` if Brand Dossier is not Active. Use when checking brand-dossier readiness before onboarding a new business.

## Inputs

| Source | Path | Purpose |
|--------|------|---------|
| Business registry | `docs/business-os/strategy/businesses.json` | Resolve app → business unit → theme package |
| Brand language | `docs/business-os/strategy/<BIZ>/brand-dossier.user.md` | Per-business visual identity, tone, audience |
| Theme tokens | `packages/themes/<theme>/src/tokens.ts` | Concrete token values for the target app |
| Base tokens | `packages/themes/base/src/tokens.ts` | Default token system (overridden by theme) |
| Design system handbook | `docs/design-system-handbook.md` | Component catalog, atomic design layers |
| Token reference | `.claude/skills/lp-design-system/SKILL.md` | Quick-reference for token classes |
| Typography & color | `docs/typography-and-color.md` | Font model, HSL system, dark mode |
| Fact-find (optional) | `docs/plans/<slug>-fact-find.md` | Feature context, audience, requirements |

### App-to-Business Resolution

Use `businesses.json` to resolve which business owns the target app, then locate:
1. **Brand language doc**: `docs/business-os/strategy/<BIZ>/brand-dossier.user.md`
2. **Theme package**: `packages/themes/<theme>/` (mapped from app name)
3. **Strategy context**: `docs/business-os/strategy/<BIZ>/plan.user.md`

**Resolution:** Read `docs/business-os/strategy/businesses.json` to resolve app → business unit → theme package. Do not use hardcoded mappings.

## Workflow

### Step 0: Context Resolution

1. **Identify the target app** from the feature slug, fact-find, or user input.
2. **Resolve business unit** via `businesses.json`.
3. **Load brand language** doc. If it doesn't exist or Status ≠ Active:
   - **STOP.** Emit GATE-BD-07 error (see Step 6).
   - Do NOT offer to proceed without brand language.
4. **Load theme tokens** for the target app's theme package.
5. **Load fact-find** if a feature slug was provided.

### Step 1: Audience and Intent

Extract from brand language + fact-find:

- **Who sees this?** Target demographic, device context, usage scenario.
- **What feeling?** Brand personality (from brand language `## Voice & Tone`).
- **What action?** Primary CTA or user goal for this feature.
- **Where in the app?** Navigation context — is this a new page, a section in an existing page, a modal, a flow?

If any of these are unclear, ask the user. Do not assume.

### Step 2: Current State Audit (Modification Only)

Skip this step for net-new pages/components.

For modifications to existing UI:
1. **Read the current component(s)** being modified.
2. **Identify existing patterns**: layout structure, component choices, token usage.
3. **Flag violations**: arbitrary values, hardcoded colors, missing dark mode, accessibility gaps.
4. **Note reusable elements**: what should be preserved vs. replaced.

### Step 3: Component Map

Using the three-tier architecture (`@acme/design-system` → `@acme/ui` → app-level):

1. **List existing components** that can be reused for this feature.
   - Search `packages/design-system/src/` for primitives/atoms/molecules.
   - Search `packages/ui/src/` for domain components.
   - Search the target app's `src/components/` for app-specific components.
2. **Identify gaps** — components that don't exist yet.
3. **Decide layer** for new components:
   - Pure presentation, no domain logic → `@acme/design-system`
   - Domain-specific (e-commerce, booking, etc.) → `@acme/ui`
   - App-specific, unlikely to be shared → app-level `src/components/`

Output a component tree showing the composition hierarchy.

### Step 4: Token Binding

For each visual property in the design, specify the exact semantic token:

| Property | Token | Value (from theme) | Rationale |
|----------|-------|---------------------|-----------|
| Primary action bg | `bg-primary` | `hsl(6 78% 57%)` | Brand coral per brand language |
| Body text | `text-foreground` | (from base) | Default readable text |
| Card surface | `bg-card` | (from base) | Standard card pattern |
| ... | ... | ... | ... |

**Rules:**
- Every color must map to a semantic token. No hex, no Tailwind palette colors.
- Reference `lp-design-system` skill for the canonical token list.
- If a needed token doesn't exist, document it as a prerequisite (new token to add to theme package).
- Dark mode: verify every chosen token has a dark variant. Flag gaps.

**Evidence requirement:** For each token binding, cite the source file and token key where the value is defined (e.g., `packages/themes/prime/src/tokens.ts → --color-primary`). If no theme package exists, cite `packages/themes/base/src/tokens.ts`.

### Step 5: Layout and Behavior

Define:

1. **Layout skeleton** — CSS Grid/Flexbox structure with responsive breakpoints.
   - Mobile-first. Specify `md:` and `lg:` breakpoint changes.
   - Use design system spacing tokens only (`gap-4`, `p-6`, etc.).
2. **Interaction states** — hover, active, disabled, loading, error, empty.
   - Map each state to token classes (e.g., `hover:bg-primary-hover`).
3. **Accessibility** — WCAG AA minimum:
   - Focus order (tab sequence).
   - ARIA roles/labels for non-standard elements.
   - Contrast compliance (note if any token combinations need checking).
   - Touch target sizes (`min-h-11 min-w-11` for interactive elements).
4. **Animation** — only if required. Use `motion-safe:` prefix. Respect `prefers-reduced-motion`.

### Step 6: Brand Dossier Pre-flight (GATE-BD-07)

**Before writing the design spec**, verify the Brand Dossier is Active:

1. **Check** `docs/business-os/strategy/<BIZ>/brand-dossier.user.md` exists AND frontmatter `Status: Active`.
2. **Check** the strategy index `docs/business-os/strategy/<BIZ>/index.user.md` — Brand Dossier row must show `Active`.

**Gate result:**

- **PASS** (Status == Active): proceed to Step 7.
- **FAIL** (missing or Status != Active): **STOP immediately.**
  - Error: `GATE-BD-07: Brand Dossier must be Active before running design spec.`
  - Remediation: `Run /lp-do-assessment-11-brand-identity --business <BIZ> to create the Brand Dossier, then have the operator promote it to Active before re-running /lp-design-spec.`
  - Do NOT create or populate brand-dossier.user.md from within this skill. That is the job of `/lp-assessment-bootstrap`.

**Note:** GATE-BD-01 at S1 advance requires brand-dossier at Draft minimum. GATE-BD-07 here requires Active. The gap (Draft → Active) is the operator's responsibility before running lp-design-spec.

### Step 7: Write Design Spec

Create `docs/plans/<feature-slug>-design-spec.md` using the template below.

### Step 8: Brand Language Feedback Loop

After completing the spec, check if any design decisions made during this spec should feed back into the brand language doc:

- **New pattern established** (e.g., "cards in this app always use `rounded-lg shadow-sm`") → add to brand language `## Signature Patterns`.
- **Token gap filled** (e.g., new token added for this business) → update brand language `## Token Overrides`.
- **Audience insight** (e.g., fact-find revealed new demographic data) → update brand language `## Audience`.

Only update with decisions that are **stable and reusable**, not one-off feature specifics.

## Design Spec Template

```markdown
---
Type: Design-Spec
Status: Draft
Feature-Slug: {slug}
Business-Unit: {BIZ}
Target-App: {app-name}
Theme-Package: {theme-package}
Brand-Language: docs/business-os/strategy/{BIZ}/brand-dossier.user.md
Created: {DATE}
Updated: {DATE}
Owner: {operator}
---

# Design Spec: {Feature Title}

## Context

**Business:** {business name} ({BIZ})
**App:** {app name}
**Audience:** {from brand language}
**Device:** {mobile-only | responsive | desktop-first}

**Feature goal:** {one sentence — what the user accomplishes}

**Fact-find:** `docs/plans/{slug}-fact-find.md` _(or "standalone spec")_

## Visual Intent

{2-3 sentences describing the desired look and feel, referencing brand language personality and any specific inspiration. Not a mockup — a north star for implementation decisions.}

## Component Map

### Reused Components

| Component | Package | Usage |
|-----------|---------|-------|
| `Button` | `@acme/design-system` | Primary CTA |
| ... | ... | ... |

### New Components Needed

| Component | Target Package | Rationale |
|-----------|---------------|-----------|
| `{Name}` | `{package}` | {why it doesn't exist yet} |

### Composition Tree

```
PageLayout
├── Header (existing)
├── {SectionName}
│   ├── {Component}
│   │   ├── {Child}
│   │   └── {Child}
│   └── {Component}
└── Footer (existing)
```

## Token Binding

| Element | Property | Token Class | Dark Mode | Notes |
|---------|----------|-------------|-----------|-------|
| Page bg | background | `bg-background` | auto | |
| Primary CTA | background | `bg-primary` | auto | Brand: {color description} |
| ... | ... | ... | ... | ... |

**New tokens required:**
- _{none, or list with rationale}_

## Layout

### Mobile (default)
{Description or ASCII sketch of mobile layout}

### Tablet (`md:` 768px+)
{Changes from mobile}

### Desktop (`lg:` 1024px+)
{Changes from tablet}

**Spacing:** {key spacing decisions, e.g., "section padding: p-6, card gap: gap-4"}

## Interaction States

| Element | Hover | Active | Disabled | Loading | Error |
|---------|-------|--------|----------|---------|-------|
| Primary CTA | `hover:bg-primary-hover` | `active:bg-primary-active` | `opacity-50 cursor-not-allowed` | spinner | - |
| ... | ... | ... | ... | ... | ... |

## Accessibility

- **Focus order:** {tab sequence description}
- **ARIA:** {roles, labels, live regions needed}
- **Contrast:** {any combinations to verify}
- **Touch targets:** All interactive elements `min-h-11 min-w-11`
- **Screen reader:** {any visually-hidden text needed}

## Prerequisites for Plan

- [ ] Brand language doc exists: `docs/business-os/strategy/{BIZ}/brand-dossier.user.md`
- [ ] Theme package exists: `packages/themes/{theme}/`
- [ ] All required tokens exist (see "New tokens required" above)
- [ ] All reused components verified in component catalog

## Notes

{Any open questions, alternatives considered, or links to reference implementations}
```

## Quality Checks

- [ ] Every color references a semantic token — zero arbitrary values
- [ ] Component map distinguishes reused vs. new, with correct package layer
- [ ] Layout specifies all three breakpoints (mobile, tablet, desktop)
- [ ] Dark mode addressed for every token binding
- [ ] Accessibility section is non-empty with concrete ARIA/focus/contrast items
- [ ] Brand Dossier Active (GATE-BD-07 pre-flight passed: Status == Active in brand-dossier.user.md)
- [ ] Token bindings match actual values in theme package (not invented)
- [ ] Prerequisites list is complete — no hidden assumptions for `/lp-do-plan`

## Integration

### With `/lp-do-fact-find`

When a fact-find classifies a feature as UI-heavy, it should add to its output:

```yaml
Design-Spec-Required: yes
```

This signals that `/lp-design-spec` should run before `/lp-do-plan`.

### With `/lp-do-plan`

Plan reads the design spec and uses it to:
- Pre-populate `Affects` lists with component file paths from the component map
- Set higher confidence on UI tasks (design decisions already made)
- Create concrete validation contracts referencing the spec's token bindings
- Generate prerequisite tasks for missing tokens or components

### With `/lp-do-build`

During build, the design spec serves as a reference:
- Exact token classes to use (no guessing)
- Component composition tree to follow
- Accessibility requirements to implement and test

### With Brand Language Docs

**Reads from:** `docs/business-os/strategy/<BIZ>/brand-dossier.user.md`
**Writes back to:** Same file, when stable new patterns emerge (Step 8).

This creates a virtuous cycle: each design spec strengthens the brand language, which makes future specs faster and more consistent.

## Hand-off Messages

### Spec Complete (has fact-find)

> Design spec complete: `docs/plans/{slug}-design-spec.md`
>
> **Component map:** {N} reused, {M} new components needed.
> **Prerequisites:** {list any blockers for plan}.
>
> Ready for `/lp-do-plan {slug}`. The plan should reference this spec for UI task confidence.

### Spec Complete (standalone)

> Design spec complete: `docs/plans/{slug}-design-spec.md`
>
> This is a standalone spec (no fact-find). To proceed:
> 1. `/lp-do-fact-find {slug}` — if the feature needs broader investigation
> 2. `/lp-do-plan {slug}` — if scope is clear and you want to go straight to planning

### GATE-BD-07 Blocked (Brand Dossier not Active)

> **GATE-BD-07:** Brand Dossier must be Active before running design spec.
>
> **Current Status:** `docs/business-os/strategy/{BIZ}/brand-dossier.user.md` is missing or Status ≠ Active.
>
> **Remediation:** Run `/lp-do-assessment-11-brand-identity --business {BIZ}` to create the Brand Dossier, then promote to Active before re-running `/lp-design-spec`.

## Red Flags (Invalid Run)

1. Spec contains arbitrary color values (`[#hex]`, `bg-red-500`, etc.)
2. Component map places domain components in `@acme/design-system`
3. No accessibility section or "N/A" without justification
4. Brand language not consulted and no explicit opt-out rationale
5. Token bindings reference tokens that don't exist in the theme package without noting them as prerequisites
6. Layout section missing responsive breakpoints