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

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

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

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>

Inputs

docs/business-os/strategy/businesses.json

docs/business-os/strategy/<BIZ>/brand-dossier.user.md

packages/themes/<theme>/src/tokens.ts

packages/themes/base/src/tokens.ts

docs/design-system-handbook.md

.claude/skills/lp-design-system/SKILL.md

docs/typography-and-color.md

docs/plans/<slug>-fact-find.md

App-to-Business Resolution

Use

businesses.json

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

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

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:

bg-primary

hsl(6 78% 57%)

text-foreground

bg-card

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

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

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

---
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:

Design-Spec-Required: yes

This signals that

/lp-design-spec

/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

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