ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/docs/learn/module-11-conceptual-specif.../lesson-01-design-is-specifi...

17 KiB
Raw Blame History

Module 11: Conceptual Specifications

Lesson 1: Page-Level Specifications

Start with the big picture, then work down

The Hierarchy of Specification

Specifications work from large to small:

┌─────────────────────────────────────────────────┐
│ LAYER 1: PAGE                                   │  ← Start here
│ Purpose, Strategy, Context                      │
│  ┌───────────────────────────────────────────┐  │
│  │ LAYER 2: SECTION                          │  │
│  │ Major areas, placement, priority          │  │
│  │  ┌─────────────────────────────────────┐  │  │
│  │  │ LAYER 3: WIDGET                     │  │  │
│  │  │ Reusable components, states         │  │  │
│  │  │  ┌───────────────────────────────┐  │  │  │
│  │  │  │ LAYER 4: CARD                 │  │  │  │
│  │  │  │ Content grouping              │  │  │  │
│  │  │  │  ┌─────────┐  ┌─────────┐    │  │  │  │
│  │  │  │  │ LAYER 5 │  │ LAYER 5 │    │  │  │  │
│  │  │  │  │ ELEMENT │  │ ELEMENT │    │  │  │  │
│  │  │  │  └─────────┘  └─────────┘    │  │  │  │
│  │  │  └───────────────────────────────┘  │  │  │
│  │  └─────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

You cannot specify a button until you understand the page.

This lesson shows you how to specify each layer, from large to small.

Layer 1: Page-Level Specification

The page is the container for everything. Specify it first.

What to Specify

Every page specification must answer:

  1. Purpose — What is this page trying to accomplish?
  2. Personas — Who is this page for?
  3. Trigger Map Connection — Which driving forces does it address?
  4. Layout Approach — Mobile-first? Desktop-first? Responsive strategy?
  5. Accessibility Requirements — WCAG level, keyboard navigation, screen reader support
  6. Performance Priorities — What loads first? What can wait?
  7. SEO Requirements — Meta descriptions, structured data, OG tags

Page Specification Format

# Page: [Page Name]
**ID:** [Page-ID]

## Purpose
[What this page accomplishes for the user]

## Personas Served
- [Persona Name]: [How this page serves them]

## Connects To
- Scenario: [Scenario ID]
- Trigger Map: [Driving Force quote]
- Feature: [Feature ID]

## Layout Strategy
- Primary Platform: [Mobile/Desktop]
- Responsive Approach: [Mobile-first/Desktop-first]
- Breakpoints: [List key breakpoints]

## Accessibility
- WCAG Level: [A/AA/AAA]
- Keyboard Navigation: [Full/Partial]
- Screen Reader: [Fully supported/Basic support]
- Focus Management: [How focus is managed on page load]

## Performance
- Priority Loading: [What loads first]
- Lazy Loading: [What loads on demand]
- Skeleton Screens: [Yes/No, where]

## SEO
- Title Tag: "[Exact title]"
- Meta Description: "[Exact description]"
- OG Tags: [Yes/No]
- Structured Data: [Schema type if applicable]

## Sections
[List of sections, detailed in Section-level specs]

Example: Signup Page Specification

# Page: Signup Page
**ID:** P01-signup-page

## Purpose
Enable Felix (persona) to create an account with minimal friction by
collecting only essential information (email + password) so he can start
trying the product immediately without lengthy onboarding.

## Personas Served
- Felix the Full-Stack: Wants to try before committing, fears complicated
  onboarding

## Connects To
- Scenario: S01-User-Registration
- Trigger Map: "I want to try this without jumping through hoops"
- Feature: F03-Quick-Signup

## Layout Strategy
- Primary Platform: Mobile
- Responsive Approach: Mobile-first
- Breakpoints: 640px (tablet), 1024px (desktop)

## Accessibility
- WCAG Level: AA
- Keyboard Navigation: Full (tab order: logo → form fields → CTA → footer links)
- Screen Reader: Fully supported
- Focus Management: Focus moves to email field on page load

## Performance
- Priority Loading: Header, hero section, form (critical path)
- Lazy Loading: Footer, testimonials (below fold)
- Skeleton Screens: No (page loads quickly, < 1s)

## SEO
- Title Tag: "Sign Up - Dog Week | Plan Your Week with Your Dog"
- Meta Description: "Create your free Dog Week account in 60 seconds.
  No credit card required. Start planning activities with your dog today."
- OG Tags: Yes (signup-og.jpg)
- Structured Data: None

## Sections
- S01: Header (Logo, Login link)
- S02: Hero (Value proposition, trust signals)
- S03: Form Area (Signup widget)
- S04: Footer (Legal links)

Notice: The page spec establishes context. We know WHO it's for (Felix), WHY it exists (minimal friction signup), and HOW it performs (mobile-first, AA accessibility).

Now we can specify sections.

Layer 2: Section-Level Specification

Sections organize the page into major areas.

What to Specify

For each section:

  1. Purpose — Why this section exists
  2. Placement — Where it appears on the page
  3. Behavior — Responsive behavior, sticky, collapsible
  4. Load Priority — When it loads relative to other sections
  5. Accessibility — Landmark role, heading structure

Section Specification Format

## Section: [Section Name]
**ID:** [Page-ID]-[Section-ID]

### Purpose
[Why this section exists]

### Placement
- Position: [Header/Above fold/Below fold/Footer]
- Responsive: [How it adapts across breakpoints]

### Behavior
- Sticky: [Yes/No]
- Collapsible: [Yes/No]
- Animation: [Entry animation if any]

### Load Priority
[Critical/High/Normal/Low]

### Accessibility
- Landmark: [role="banner/main/navigation/contentinfo/complementary"]
- Heading: [h1/h2/h3 - what level starts this section]

### Contains
[List of widgets/cards in this section]

Example: Hero Section Specification

## Section: Hero Section
**ID:** P01-S02-hero-section

### Purpose
Communicate value proposition quickly to reduce Felix's hesitation and
make the benefit of signing up immediately clear.

### Placement
- Position: Above fold, immediately after header
- Responsive:
  - Mobile: Stacked vertically (headline → subtext → visual)
  - Tablet: Side-by-side (text left, visual right, 60/40 split)
  - Desktop: Same as tablet

### Behavior
- Sticky: No
- Collapsible: No
- Animation: Fade in on page load (300ms ease-in)

### Load Priority
Critical (above fold, visible immediately)

### Accessibility
- Landmark: role="main"
- Heading: h1 (main page headline)

### Contains
- W01: Value Proposition Widget (headline + subtext)
- No cards or complex widgets, just text + image

Notice: The section spec explains WHERE it appears and HOW it behaves. We haven't specified the exact content yet — that comes at the widget/element level.

Layer 3: Widget-Level Specification

Widgets are reusable components that can appear in multiple places.

What to Specify

For each widget:

  1. Reusability — Where else does this widget appear?
  2. States — All possible states (default, loading, error, etc.)
  3. Validation — What rules apply?
  4. Accessibility — ARIA patterns, keyboard interactions
  5. Content Structure — What content slots does it have?

Widget Specification Format

## Widget: [Widget Name]
**ID:** [Page-ID]-[Section-ID]-[Widget-ID]

### Purpose
[What this widget accomplishes]

### Used In
- [List of pages/sections where this widget appears]

### States
- [State name]: [Description]

### Validation
[Validation rules if applicable]

### Accessibility
- ARIA Pattern: [Combobox/Dialog/Tabs/etc.]
- Keyboard: [Key interactions]
- Focus: [Focus management]

### Content Structure
[Slots or content areas]

### Elements
[List of child elements, detailed in Element-level specs]

Example: Signup Form Widget

## Widget: Signup Form
**ID:** P01-S03-W01-signup-form

### Purpose
Collect minimal information (email + password) to create account
with real-time validation to prevent submission errors.

### Used In
- P01-signup-page (Section S03)
- Modal signup (when triggered from marketing pages)
- Embedded signup (partner sites)

### States
- Default: Empty form, submit button enabled
- Filling: Real-time validation as user types
- Validating: Check email availability (async)
- Invalid: Error messages shown, submit disabled
- Submitting: Loading state, form locked
- Success: Confirmation message, redirect after 1.5s
- Error: Server error message, form re-enabled

### Validation
- Email: Valid format, check availability against database
- Password: Minimum 8 characters, show strength indicator

### Accessibility
- ARIA Pattern: Form with live regions for validation
- Keyboard: Tab order: email → password → show password toggle → submit
- Focus: On error, focus moves to first invalid field
- Screen Reader: Error messages announced via aria-live="assertive"

### Content Structure
- Form heading slot
- Email field slot
- Password field slot
- Submit button slot
- Error message slot
- Terms acceptance slot

### Elements
- E01: Email Field
- E02: Password Field
- E03: Show Password Toggle
- E04: Password Strength Indicator
- E05: Submit Button
- E06: Terms Link

Notice: The widget spec defines WHAT it does and WHERE it's used. It's specified once but can be reused anywhere. States and validation rules are explicit.

Layer 4: Card-Level Specification

Cards group related content into repeatable patterns.

What to Specify

For each card:

  1. Content Pattern — What information does it display?
  2. Data Structure — What data feeds into it?
  3. Repetition — How many instances appear?
  4. Interaction — Is it clickable? Expandable?

Card Specification Format

## Card: [Card Name]
**ID:** [Page-ID]-[Section-ID]-[Card-ID]

### Purpose
[What this card displays]

### Data Structure
[What data it receives]

### Instances
[How many appear, or is it a template]

### Interaction
[Clickable/Static/Expandable]

### Elements
[List of elements within the card]

Example: Feature Card

## Card: Feature Card
**ID:** P01-S04-C01-feature-card

### Purpose
Display one product feature with icon, title, and description to
build trust before signup.

### Data Structure
```json
{
  "icon": "string (icon name)",
  "title": "string",
  "description": "string (max 120 chars)"
}

Instances

Template card, rendered 3 times with different data

Interaction

Static (not clickable)

Elements

  • E01: Feature Icon
  • E02: Feature Title
  • E03: Feature Description

**Notice:** Cards define the PATTERN for grouped content. The data structure shows what feeds into each instance.

---

## Layer 5: Element-Level Specification

Elements are the smallest specifiable units: buttons, fields, icons, labels.

### What to Specify

For each element:

1. **All States** — Every possible state it can be in
2. **Content** — Exact text (not lorem ipsum)
3. **ARIA Attributes** — Specific accessibility properties
4. **Behavior** — What happens on interaction
5. **Translations** — Content in all supported languages

### Element Specification Format

```markdown
## Element: [Element Name]
**ID:** [Full-Hierarchy-ID]

### Type
[Button/Input/Icon/Label/Link]

### States
- Default: [Description]
- [Other states]: [Description]

### Content
- Label: "[Exact text]"
- Translations:
  - ES: "[Spanish text]"
  - DE: "[German text]"

### ARIA
- role: "[Role]"
- aria-label: "[Label]"
- aria-required: "[true/false]"
- [Other ARIA attributes]

### Behavior
[What happens when user interacts]

Example: Email Field Element

## Element: Email Field
**ID:** P01-S03-W01-E01-email-field

### Type
Text input (email)

### States
- Default: Empty, placeholder visible
- Focused: Border highlight, placeholder fades
- Typing: Real-time format validation
- Valid: Green checkmark appears
- Invalid: Red border, error message below
- Disabled: Grayed out (during submission)

### Content
- Label: "Email"
- Placeholder: "you@company.com"
- Error Message (invalid format): "Please enter a valid email address"
- Error Message (taken): "This email is already registered. [Log in instead →]"
- Translations:
  - ES:
    - Label: "Correo electrónico"
    - Placeholder: "tu@empresa.com"
    - Error (invalid): "Por favor, introduce una dirección de correo válida"
    - Error (taken): "Este correo ya está registrado. [Iniciar sesión →]"

### ARIA
- role: "textbox"
- aria-label: "Email address for your account"
- aria-required: "true"
- aria-invalid: "false" (default) → "true" (when error)
- aria-describedby: "email-error" (when error message shown)

### Behavior
- On focus: Placeholder fades to 50% opacity
- On blur: Validate email format
- On change (after 1s delay): Check email availability (async)
- On error: Focus remains in field, error announced to screen reader

Notice: The element spec is COMPLETE. A developer can build this exactly from the specification without asking questions.

The Pattern

Working from large to small ensures:

Page establishes:     → WHY this exists, WHO it's for
  ↓
Sections establish:   → WHERE things appear, WHEN they load
  ↓
Widgets establish:    → WHAT can be reused, HOW it validates
  ↓
Cards establish:      → PATTERN for grouped content
  ↓
Elements establish:   → EXACT implementation details

You cannot specify an element without understanding the widget. You cannot specify a widget without understanding the section. You cannot specify a section without understanding the page.

IDs Connect the Hierarchy

P01-signup-page
│
├── P01-S01-header-section
│   └── P01-S01-W01-logo-link
│       └── P01-S01-W01-E01-logo-image
│
├── P01-S02-hero-section
│   └── P01-S02-W01-value-prop-widget
│       ├── P01-S02-W01-E01-headline
│       └── P01-S02-W01-E02-subtext
│
├── P01-S03-form-section
│   └── P01-S03-W01-signup-form
│       ├── P01-S03-W01-E01-email-field
│       ├── P01-S03-W01-E02-password-field
│       ├── P01-S03-W01-E03-show-password-toggle
│       ├── P01-S03-W01-E04-strength-indicator
│       └── P01-S03-W01-E05-submit-button
│
└── P01-S04-footer-section
    ├── P01-S04-W01-legal-links
    └── P01-S04-C01-feature-card (template, 3 instances)
        ├── P01-S04-C01-E01-icon
        ├── P01-S04-C01-E02-title
        └── P01-S04-C01-E03-description

Every ID traces from page to element. This is your implementation map.

Completeness Test

Your specification is complete when:

✅ A developer can build the page without asking questions ✅ A translator can extract all content and know where it appears ✅ A tester can verify every state in every element ✅ An accessibility auditor can validate all ARIA attributes ✅ A designer returning 6 months later can understand every decision

If any role needs to guess, the spec is incomplete.

Common Mistakes

Mistake Why It Fails Fix
Starting with buttons No context for decisions Start with page purpose
Skipping sections Don't know where widgets appear Always specify section first
Forgetting states Bugs in edge cases Document all states
Lorem ipsum content Can't plan for translations Write real copy
No IDs Can't trace to implementation ID everything from page to element

What's Next

In Lesson 2, you'll learn how to specify sections and widgets in detail, including advanced patterns for complex components.

In Lesson 3, you'll learn how to specify elements and states completely, covering all edge cases and accessibility requirements.

Continue to Lesson 2: Section & Widget Specifications →

← Back to Module Overview

Part of Module 11: Conceptual Specifications