chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,333 @@
|
||||
# Freya's Design System Guide
|
||||
|
||||
**When to load:** When Phase 7 (Design System) is enabled and component questions arise
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Design systems grow organically - discover components through actual work, never create speculatively.**
|
||||
|
||||
---
|
||||
|
||||
## Three Design System Modes
|
||||
|
||||
### Mode A: No Design System
|
||||
**What it means:**
|
||||
- All components stay page-specific
|
||||
- No component extraction
|
||||
- AI/dev team handles consistency
|
||||
- Faster for simple projects
|
||||
|
||||
**When this workflow doesn't run:**
|
||||
- Phase 7 is disabled
|
||||
- Components reference page context only
|
||||
|
||||
**Agent behavior:**
|
||||
- Create components as page-specific
|
||||
- Use clear, descriptive class names
|
||||
- No need to think about reusability
|
||||
|
||||
---
|
||||
|
||||
### Mode B: Custom Figma Design System
|
||||
**What it means:**
|
||||
- Designer defines components in Figma
|
||||
- Components extracted as discovered during Phase 4
|
||||
- Figma MCP endpoints for integration
|
||||
- Component IDs link spec ↔ Figma
|
||||
|
||||
**Workflow:**
|
||||
1. Designer creates component in Figma
|
||||
2. Component discovered during page design
|
||||
3. Agent links to Figma via Component ID
|
||||
4. Specification references Figma source
|
||||
|
||||
**See:** `skill:wds-6-asset-generation` → workflow-figma.md
|
||||
|
||||
---
|
||||
|
||||
### Mode C: Component Library Design System
|
||||
**What it means:**
|
||||
- Uses shadcn/Radix/similar library
|
||||
- Library chosen during setup
|
||||
- Components mapped to library defaults
|
||||
- Variants customized as needed
|
||||
|
||||
**Workflow:**
|
||||
1. Component needed during page design
|
||||
2. Check if library has it (button, input, card, etc.)
|
||||
3. Map to library component
|
||||
4. Document customizations (if any)
|
||||
|
||||
---
|
||||
|
||||
## The Design System Router
|
||||
|
||||
**Runs automatically during Phase 4 component specification**
|
||||
|
||||
**For each component:**
|
||||
1. Check: Design system enabled? (Mode B or C)
|
||||
2. If NO → Create page-specific, continue
|
||||
3. If YES → Call design-system-router.md
|
||||
|
||||
**Router asks:**
|
||||
- Is this component new?
|
||||
- Is there a similar component?
|
||||
- Should we create new or use/extend existing?
|
||||
|
||||
**See:** `skill:wds-7-design-system` → design-system-router.md
|
||||
|
||||
---
|
||||
|
||||
## Never Create Components Speculatively
|
||||
|
||||
### ❌ Wrong Approach
|
||||
"Let me create a full component library upfront..."
|
||||
|
||||
**Why bad:**
|
||||
- You don't know what you'll actually need
|
||||
- Over-engineering
|
||||
- Wasted effort on unused components
|
||||
|
||||
---
|
||||
|
||||
### ✅ Right Approach
|
||||
"I'm designing the landing page hero... oh, I need a button."
|
||||
|
||||
**Process:**
|
||||
1. Design the button for this specific page
|
||||
2. When another page needs a button → Opportunity!
|
||||
3. Assess: Similar enough to extract?
|
||||
4. Extract to Design System if makes sense
|
||||
|
||||
**Result:** Components emerge from real needs.
|
||||
|
||||
---
|
||||
|
||||
## Opportunity/Risk Assessment
|
||||
|
||||
**When similar component exists, run assessment:**
|
||||
|
||||
**See:** `skill:wds-7-design-system` → assessment/
|
||||
|
||||
**7 Micro-Steps:**
|
||||
1. Scan existing components
|
||||
2. Compare attributes (visual, behavior, states)
|
||||
3. Calculate similarity score
|
||||
4. Identify opportunities (reuse, consistency)
|
||||
5. Identify risks (divergence, complexity)
|
||||
6. Present decision to designer
|
||||
7. Execute decision
|
||||
|
||||
**Outcomes:**
|
||||
- **Use existing** - Component is close enough
|
||||
- **Create variant** - Extend existing with new state
|
||||
- **Create new** - Too different, warrants separate component
|
||||
- **Update existing** - Existing is too narrow, expand it
|
||||
|
||||
---
|
||||
|
||||
## Foundation First
|
||||
|
||||
**Before any components:**
|
||||
|
||||
### 1. Design Tokens
|
||||
```
|
||||
Design tokens = the DNA of your design system
|
||||
|
||||
Colors:
|
||||
- Primary, secondary, accent
|
||||
- Neutral scale (50-900)
|
||||
- Semantic (success, warning, error, info)
|
||||
|
||||
Typography:
|
||||
- Font families
|
||||
- Font scales (h1-h6, body, caption)
|
||||
- Font weights
|
||||
- Line heights
|
||||
|
||||
Spacing:
|
||||
- Spacing scale (xs, sm, md, lg, xl)
|
||||
- Layout scales
|
||||
|
||||
Effects:
|
||||
- Border radius scale
|
||||
- Shadow scale
|
||||
- Transitions
|
||||
```
|
||||
|
||||
**Why first:** Tokens ensure consistency across all components.
|
||||
|
||||
---
|
||||
|
||||
### 2. Atomic Design Structure
|
||||
|
||||
**Organize from simple → complex:**
|
||||
|
||||
```
|
||||
atoms/
|
||||
├── button.md
|
||||
├── input.md
|
||||
├── label.md
|
||||
├── icon.md
|
||||
└── badge.md
|
||||
|
||||
molecules/
|
||||
├── form-field.md (label + input + error)
|
||||
├── card.md (container + content)
|
||||
└── search-box.md (input + button + icon)
|
||||
|
||||
organisms/
|
||||
├── header.md (logo + nav + search + user-menu)
|
||||
├── feature-section.md (headline + cards + cta)
|
||||
└── form.md (multiple form-fields + submit)
|
||||
```
|
||||
|
||||
**Why this structure:** Clear dependencies, easy to understand, scales well.
|
||||
|
||||
---
|
||||
|
||||
## Component Operations
|
||||
|
||||
**See:** `skill:wds-7-design-system` → operations/
|
||||
|
||||
### 1. Initialize Design System
|
||||
**First component triggers auto-initialization**
|
||||
- Creates folder structure
|
||||
- Creates design-tokens.md
|
||||
- Creates component-library-config.md (if Mode C)
|
||||
|
||||
### 2. Create New Component
|
||||
- Defines component specification
|
||||
- Assigns Component ID
|
||||
- Documents states and variants
|
||||
- Notes where used
|
||||
|
||||
### 3. Add Variant
|
||||
- Extends existing component
|
||||
- Documents variant trigger
|
||||
- Updates component spec
|
||||
|
||||
### 4. Update Component
|
||||
- Modifies existing definition
|
||||
- Increments version
|
||||
- Documents change rationale
|
||||
|
||||
---
|
||||
|
||||
## Component Specification Template
|
||||
|
||||
```markdown
|
||||
# [Component Name] [COMP-001]
|
||||
|
||||
**Type:** [Atom|Molecule|Organism]
|
||||
**Library:** [shadcn Button|Custom|N/A]
|
||||
**Figma:** [Link if Mode B]
|
||||
|
||||
## Purpose
|
||||
[What job does this component do?]
|
||||
|
||||
## Variants
|
||||
- variant-name: [When to use]
|
||||
- variant-name: [When to use]
|
||||
|
||||
## States
|
||||
- default
|
||||
- hover
|
||||
- active
|
||||
- disabled
|
||||
- loading (if applicable)
|
||||
- error (if applicable)
|
||||
|
||||
## Props/Attributes
|
||||
| Prop | Type | Default | Description |
|
||||
|------|------|---------|-------------|
|
||||
| size | sm\|md\|lg | md | Button size |
|
||||
| variant | primary\|secondary | primary | Visual style |
|
||||
|
||||
## Styling
|
||||
[Design tokens or Figma reference]
|
||||
|
||||
## Used In
|
||||
- [Page name] ([Component purpose in context])
|
||||
- [Page name] ([Component purpose in context])
|
||||
|
||||
## Version History
|
||||
- v1.0.0 (2024-01-01): Initial creation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 4
|
||||
|
||||
**Phase 4 (UX Design) → Phase 7 (Design System) flow:**
|
||||
|
||||
```
|
||||
User creates page specification
|
||||
├── Component 1: Button
|
||||
│ ├── Check: Design system enabled?
|
||||
│ ├── YES → Router checks existing components
|
||||
│ ├── Similar button found → Opportunity/Risk Assessment
|
||||
│ └── Decision: Use existing primary button variant
|
||||
├── Component 2: Input
|
||||
│ ├── Check: Design system enabled?
|
||||
│ ├── YES → Router checks existing components
|
||||
│ ├── No similar input → Create new
|
||||
│ └── Add to Design System
|
||||
└── Component 3: Custom illustration
|
||||
├── Check: Design system enabled?
|
||||
└── NO extraction (one-off asset)
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- Page spec contains references + page-specific content
|
||||
- Design System contains component definitions
|
||||
- Clean separation maintained
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Creating Library Before Designing
|
||||
"Let me make 50 components upfront..."
|
||||
- **Instead:** Design pages, extract components as needed
|
||||
|
||||
### ❌ Over-Abstracting Too Early
|
||||
"This button might need 10 variants someday..."
|
||||
- **Instead:** Start simple, add variants when actually needed
|
||||
|
||||
### ❌ Forcing Reuse
|
||||
"I'll make this work even though it's awkward..."
|
||||
- **Instead:** Sometimes a new component is better than a forced variant
|
||||
|
||||
### ❌ No Design Tokens
|
||||
"I'll define colors per component..."
|
||||
- **Instead:** Tokens first, components second
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before marking a component "complete":
|
||||
|
||||
- [ ] **Clear purpose** - What job does it do?
|
||||
- [ ] **Design tokens** - Uses tokens, not hard-coded values?
|
||||
- [ ] **All states** - Default, hover, active, disabled documented?
|
||||
- [ ] **Variants** - Each variant has clear use case?
|
||||
- [ ] **Reusability** - Can be used in multiple contexts?
|
||||
- [ ] **Documentation** - Specification is complete?
|
||||
- [ ] **Examples** - Shows where it's actually used?
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Phase 7 Workflow:** `skill:wds-7-design-system`
|
||||
- **Figma Integration:** `skill:wds-6-asset-generation` → workflow-figma.md
|
||||
- **Shared Knowledge:** design-system data (tokens, naming, states, validation, boundaries)
|
||||
|
||||
---
|
||||
|
||||
*Components emerge from real needs. Design systems grow organically.*
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
# Freya's Specification Quality Guide
|
||||
|
||||
**When to load:** Before creating any page spec, component definition, or scenario documentation
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**If I can't explain it logically, it's not ready to specify.**
|
||||
|
||||
Gaps in logic become bugs in code. Clear specifications = confident implementation.
|
||||
|
||||
---
|
||||
|
||||
## The Logical Explanation Test
|
||||
|
||||
Before you write any specification, ask:
|
||||
|
||||
**"Can I explain WHY this exists and HOW it works without hand-waving?"**
|
||||
|
||||
- ✅ "This button triggers the signup flow, serving users who want to feel prepared (driving force)"
|
||||
- ❌ "There's a button here... because users need it?"
|
||||
|
||||
**If you can't explain it clearly, stop and think deeper.**
|
||||
|
||||
---
|
||||
|
||||
## Area Label Structure & Hierarchy
|
||||
|
||||
**Area Labels follow a consistent hierarchical pattern to identify UI locations across sketch, specification, and code.**
|
||||
|
||||
### Structural Area Labels (Containers)
|
||||
These define the page architecture and visual grouping:
|
||||
|
||||
- `{page-name}-page` - Top-level page wrapper
|
||||
- `{page-name}-header` - Header section container
|
||||
- `{page-name}-main` - Main content area
|
||||
- `{page-name}-form` - Form element wrapper
|
||||
- `{page-name}-{section}-section` - Section containers
|
||||
- `{page-name}-{section}-header-bar` - Section header bars
|
||||
|
||||
**Purpose:** Organize page structure, enable Figma layer naming (via aria-label), support testing selectors (via id attribute)
|
||||
|
||||
### Interactive Area Labels (Components)
|
||||
These identify specific interactive elements:
|
||||
|
||||
- `{page-name}-{section}-{element}` - Standard pattern
|
||||
- `{page-name}-input-{field}` - Form inputs
|
||||
- `{page-name}-button-{action}` - Buttons
|
||||
- `{page-name}-error-{field}` - Error messages
|
||||
|
||||
**Purpose:** Enable user interaction, form validation, accessibility, and location tracking across design and code
|
||||
|
||||
**Note:** Area Labels become both `id` and `aria-label` attributes in HTML implementation.
|
||||
|
||||
### Purpose-Based Naming
|
||||
|
||||
**Name components by FUNCTION, not CONTENT**
|
||||
|
||||
### Good (Function)
|
||||
- `hero-headline` - Describes its role on the page
|
||||
- `primary-cta` - Describes its function in the flow
|
||||
- `feature-benefit-section` - Describes what it does
|
||||
- `form-validation-error` - Describes when it appears
|
||||
|
||||
### Bad (Content)
|
||||
- `welcome-message` - What if the message changes?
|
||||
- `blue-button` - What if we change colors?
|
||||
- `first-paragraph` - Position isn't purpose
|
||||
- `email-error-text` - Too specific, not reusable
|
||||
|
||||
**Why this matters:**
|
||||
- Content changes, function rarely does
|
||||
- Makes specs maintainable
|
||||
- Helps developers understand intent
|
||||
- Enables component reuse
|
||||
- Supports Figma html.to.design layer naming
|
||||
|
||||
---
|
||||
|
||||
## Clear Component Purpose
|
||||
|
||||
**Every component needs a clear job description:**
|
||||
|
||||
### Template
|
||||
```markdown
|
||||
### [Component Name]
|
||||
|
||||
**Purpose:** [What job does this do?]
|
||||
**Triggers:** [What user action/state causes this?]
|
||||
**Serves:** [Which driving force or goal?]
|
||||
**Success:** [How do we know it worked?]
|
||||
```
|
||||
|
||||
### Example
|
||||
```markdown
|
||||
### Primary CTA Button
|
||||
|
||||
**Purpose:** Initiate account creation flow
|
||||
**Triggers:** User clicks after reading value proposition
|
||||
**Serves:** User's desire to "feel prepared" (positive driving force)
|
||||
**Success:** User enters email and moves to step 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section-First Workflow
|
||||
|
||||
**Understand the WHOLE before detailing the PARTS**
|
||||
|
||||
### Wrong Approach (Bottom-Up)
|
||||
1. Design individual components
|
||||
2. Try to arrange them into sections
|
||||
3. Hope the page makes sense
|
||||
4. Realize it doesn't flow logically
|
||||
5. Start over
|
||||
|
||||
### Right Approach (Top-Down)
|
||||
1. **Define structural containers** - Page, header, main, sections
|
||||
2. **Assign structural Area Labels** - `{page}-page`, `{page}-header`, etc.
|
||||
3. **Identify page sections** - What major areas exist?
|
||||
4. **Define section purposes** - Why does each section exist?
|
||||
5. **Confirm flow logic** - Does the story make sense?
|
||||
6. **Detail each section** - Now design components
|
||||
7. **Specify components** - With clear purpose and context
|
||||
8. **Assign interactive Area Labels** - `{page}-{section}-{element}`
|
||||
|
||||
**Result:** Logical flow, no gaps, confident specifications, complete Area Label coverage
|
||||
|
||||
### Area Label Coverage Checklist
|
||||
- [ ] Page container (`{page}-page`)
|
||||
- [ ] Header section (`{page}-header`)
|
||||
- [ ] Main content area (`{page}-main`)
|
||||
- [ ] Form container if applicable (`{page}-form`)
|
||||
- [ ] Section containers (`{page}-{section}-section`)
|
||||
- [ ] Section header bars if visible (`{page}-{section}-header-bar`)
|
||||
- [ ] All interactive elements (`{page}-{section}-{element}`)
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language from the Start
|
||||
|
||||
**Never design in one language only**
|
||||
|
||||
### Grouped Translations
|
||||
```markdown
|
||||
#### Hero Headline
|
||||
|
||||
**Content:**
|
||||
- EN: "Stop losing clients to poor proposals"
|
||||
- SE: "Sluta förlora kunder på dåliga offerter"
|
||||
- NO: "Slutt å miste kunder på dårlige tilbud"
|
||||
|
||||
**Purpose:** Hook Problem Aware users by validating frustration
|
||||
```
|
||||
|
||||
### Why This Matters
|
||||
- Prevents "English-first" bias
|
||||
- Reveals translation issues early
|
||||
- Shows if message works across cultures
|
||||
- Keeps translations coherent (grouped by component)
|
||||
|
||||
---
|
||||
|
||||
## Specification Quality Checklist
|
||||
|
||||
Before marking a spec "complete":
|
||||
|
||||
### Core Quality
|
||||
- [ ] **Logical Explanation** - Can I explain WHY and HOW?
|
||||
- [ ] **Purpose-Based Names** - Named by function, not content?
|
||||
- [ ] **Clear Purpose** - Every component has a job description?
|
||||
- [ ] **Section-First** - Whole page flows logically?
|
||||
- [ ] **Multi-Language** - All product languages included?
|
||||
- [ ] **No Hand-Waving** - No "probably" or "maybe" or "users will figure it out"?
|
||||
|
||||
### Area Labels
|
||||
- [ ] **Structural Area Labels** - Page, header, main, sections all have labels?
|
||||
- [ ] **Interactive Area Labels** - All buttons, inputs, links have labels?
|
||||
- [ ] **Area Label Hierarchy** - Labels follow `{page}-{section}-{element}` pattern?
|
||||
- [ ] **Figma-Ready** - Area Labels support html.to.design layer naming?
|
||||
|
||||
### Accessibility
|
||||
- [ ] **ARIA Labels** - All interactive elements have aria-label attributes?
|
||||
- [ ] **Alt Text** - All images have descriptive alt attributes?
|
||||
- [ ] **Form Labels** - All inputs have associated labels?
|
||||
- [ ] **Keyboard Navigation** - Tab order and focus management documented?
|
||||
- [ ] **Screen Reader Support** - Semantic HTML and ARIA attributes specified?
|
||||
- [ ] **Color Contrast** - WCAG AA compliance (4.5:1 for text)?
|
||||
- [ ] **Error Announcements** - Error messages accessible to screen readers?
|
||||
- [ ] **Heading Hierarchy** - Logical H1-H6 structure documented?
|
||||
|
||||
### SEO (Public Pages)
|
||||
- [ ] **H1 Present** - Exactly one H1 on the page, contains primary keyword?
|
||||
- [ ] **Heading Hierarchy** - Logical H1 → H2 → H3, no skipped levels?
|
||||
- [ ] **URL Slug** - Defined, keyword-rich, matches project brief keyword map?
|
||||
- [ ] **Primary Keyword** - Identified and placed in H1, title tag, meta description?
|
||||
- [ ] **Meta Title** - ≤ 60 chars, includes primary keyword + brand?
|
||||
- [ ] **Meta Description** - 150-160 chars, includes keyword + CTA?
|
||||
- [ ] **Image Alt Text** - All images have descriptive alt text in all languages?
|
||||
- [ ] **Internal Links** - At least 2 links to other pages on the site?
|
||||
- [ ] **Structured Data** - Schema type specified per project brief plan?
|
||||
|
||||
### Content Completeness
|
||||
- [ ] **All Text Defined** - No placeholder content?
|
||||
- [ ] **Error Messages** - All error states have messages in all languages?
|
||||
- [ ] **Success Messages** - Confirmation messages defined?
|
||||
- [ ] **Empty States** - Messages for no-data scenarios?
|
||||
- [ ] **Loading States** - Loading indicators and messages?
|
||||
- [ ] **Meta Content** - Page title and meta description for public pages?
|
||||
- [ ] **Social Sharing** - Social media title, description, and image for public pages?
|
||||
|
||||
### Implementation Ready
|
||||
- [ ] **Developer-Ready** - Could someone build this confidently?
|
||||
- [ ] **Component References** - All design system components linked?
|
||||
- [ ] **API Endpoints** - Data requirements documented?
|
||||
- [ ] **Validation Rules** - Form validation clearly specified?
|
||||
|
||||
---
|
||||
|
||||
## Red Flags (Stop and Rethink)
|
||||
|
||||
🚩 **Vague language:** "Something here to help users understand..."
|
||||
🚩 **Content-based names:** "blue-box", "top-paragraph"
|
||||
🚩 **Missing purpose:** "There's a button... because buttons are good?"
|
||||
🚩 **Illogical flow:** "This section comes after that one... because?"
|
||||
🚩 **English-only:** "We'll translate later..."
|
||||
🚩 **Gaps in logic:** "Users will just know what to do here"
|
||||
🚩 **Missing accessibility:** "We'll add ARIA labels during development..."
|
||||
🚩 **No alt text:** Images without descriptive alternatives
|
||||
🚩 **Unlabeled inputs:** Form fields without associated labels
|
||||
🚩 **No SEO section:** Public page without URL slug, keywords, or meta content
|
||||
|
||||
**When you spot these, pause and dig deeper.**
|
||||
|
||||
---
|
||||
|
||||
## The Developer Trust Test
|
||||
|
||||
**Imagine handing your spec to a developer who:**
|
||||
- Has never seen your sketches
|
||||
- Doesn't know the business context
|
||||
- Speaks a different language
|
||||
- Lives in a different timezone
|
||||
|
||||
**Could they build this confidently?**
|
||||
|
||||
- ✅ Yes → Good spec
|
||||
- ❌ No → More work needed
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **File Naming:** `skill:wds-0-project-setup` → FILE-NAMING-CONVENTIONS.md
|
||||
- **Language Config:** `skill:wds-0-project-setup` → language-configuration-guide.md
|
||||
- **Page Spec Template:** `./resources/wds-4-ux-design/templates/page-specification.template.md`
|
||||
|
||||
---
|
||||
|
||||
*Quality specifications are the foundation of confident implementation.*
|
||||
|
||||
Reference in New Issue
Block a user