version: "1.0.1" name: lp-design-spec description: Translate a feature requirement into a concrete frontend design specification mapped to the design system, theme tokens, and per-business brand language. Sits between fact-find and plan.

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

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.

1. Load theme tokens for the target app's theme package.
2. 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.

1. Identify gaps — components that don't exist yet.
2. 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:

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

1. Interaction states — hover, active, disabled, loading, error, empty.

• Map each state to token classes (e.g., hover:bg-primary-hover).

1. 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).

1. 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

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