Skill v1.0.1
currentLLM-judged scan95/1001 files
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-planproduces 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:
- Brand language doc:
docs/business-os/strategy/<BIZ>/brand-dossier.user.md - Theme package:
packages/themes/<theme>/(mapped from app name) - 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
- Identify the target app from the feature slug, fact-find, or user input.
- Resolve business unit via
businesses.json. - 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.
- Load theme tokens for the target app's theme package.
- 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:
- Read the current component(s) being modified.
- Identify existing patterns: layout structure, component choices, token usage.
- Flag violations: arbitrary values, hardcoded colors, missing dark mode, accessibility gaps.
- 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):
- 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.
- Identify gaps — components that don't exist yet.
- 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-systemskill 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:
- Layout skeleton — CSS Grid/Flexbox structure with responsive breakpoints.
- Mobile-first. Specify
md:andlg:breakpoint changes. - Use design system spacing tokens only (
gap-4,p-6, etc.).
- Interaction states — hover, active, disabled, loading, error, empty.
- Map each state to token classes (e.g.,
hover:bg-primary-hover).
- 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-11for interactive elements).
- Animation — only if required. Use
motion-safe:prefix. Respectprefers-reduced-motion.
Step 6: Brand Dossier Pre-flight (GATE-BD-07)
Before writing the design spec, verify the Brand Dossier is Active:
- Check
docs/business-os/strategy/<BIZ>/brand-dossier.user.mdexists AND frontmatterStatus: Active. - Check the strategy index
docs/business-os/strategy/<BIZ>/index.user.md— Brand Dossier row must showActive.
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-SpecStatus: DraftFeature-Slug: {slug}Business-Unit: {BIZ}Target-App: {app-name}Theme-Package: {theme-package}Brand-Language: docs/business-os/strategy/{BIZ}/brand-dossier.user.mdCreated: {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
Affectslists 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.mdComponent 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.mdThis is a standalone spec (no fact-find). To proceed:1./lp-do-fact-find {slug}— if the feature needs broader investigation2./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.mdis 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)
- Spec contains arbitrary color values (
[#hex],bg-red-500, etc.) - Component map places domain components in
@acme/design-system - No accessibility section or "N/A" without justification
- Brand language not consulted and no explicit opt-out rationale
- Token bindings reference tokens that don't exist in the theme package without noting them as prerequisites
- Layout section missing responsive breakpoints