devstack 0.1.0

package/vendor/skills/skills/design-spec-extraction/references/extraction-patterns.md

@@ -0,0 +1,1044 @@
+# Design Specification Extraction Patterns
+
+This reference provides comprehensive patterns for extracting design specifications from visual sources (screenshots, Figma exports, mockups).
+
+## Table of Contents
+
+1. [Visual Analysis Fundamentals](#visual-analysis-fundamentals)
+2. [Layout Detection Patterns](#layout-detection-patterns)
+3. [Component Detection Patterns](#component-detection-patterns)
+4. [Color Extraction Patterns](#color-extraction-patterns)
+5. [Typography Extraction Patterns](#typography-extraction-patterns)
+6. [Spacing and Dimensions Patterns](#spacing-and-dimensions-patterns)
+7. [State Inference Rules](#state-inference-rules)
+8. [Accessibility Analysis Patterns](#accessibility-analysis-patterns)
+9. [Component Classification Taxonomy](#component-classification-taxonomy)
+10. [Confidence Scoring](#confidence-scoring)
+11. [Output Format Conversions](#output-format-conversions)
+
+---
+
+## Visual Analysis Fundamentals
+
+### Image Preprocessing Considerations
+
+Before extraction, assess the source image:
+
+**1. Resolution Assessment**
+
+- High resolution (2x/3x): Scale coordinates by density factor
+- Low resolution: Note reduced confidence in fine details
+- Variable density: Normalize to 1x for consistent measurements
+
+**2. Source Type Identification**
+
+| Source Type        | Characteristics                     | Confidence Impact |
+| ------------------ | ----------------------------------- | ----------------- |
+| Figma Export       | Clean vectors, precise measurements | High              |
+| Website Screenshot | May include browser chrome          | Medium-High       |
+| Mockup/Wireframe   | Lower fidelity, focus on structure  | Medium            |
+| Mobile Screenshot  | Status bar, navigation gestures     | Medium            |
+| Photo of Screen    | Perspective issues, artifacts       | Low               |
+
+**3. Content Area Detection**
+
+- Identify actual design area vs. surrounding artifacts
+- Browser chrome, device frames should be excluded from analysis
+- Status bars, navigation bars may or may not be part of design
+
+### Hierarchical Decomposition Strategy
+
+Extract structure using depth-first analysis:
+
+```
+1. Identify major regions (header, main, sidebar, footer)
+2. Within each region, identify containers/sections
+3. Within containers, identify individual components
+4. Within components, identify atomic elements
+5. Validate parent-child containment relationships
+```
+
+---
+
+## Layout Detection Patterns
+
+### Viewport Classification
+
+| Aspect Ratio | Width Range | Classification                  |
+| ------------ | ----------- | ------------------------------- |
+| < 0.6        | < 480px     | Mobile Portrait                 |
+| 0.6 - 0.8    | 480-768px   | Mobile Landscape / Small Tablet |
+| 0.8 - 1.2    | 768-1024px  | Tablet                          |
+| > 1.2        | > 1024px    | Desktop                         |
+
+### Primary Layout Types
+
+#### Single Column Layout
+
+**Visual Indicators:**
+
+- Content centered horizontally
+- Elements stacked vertically
+- Consistent left/right margins
+- Maximum width constraint visible
+
+#### Multi-Column Grid
+
+**Visual Indicators:**
+
+- Visible column divisions (2, 3, 4, or 12-column)
+- Consistent gutter spacing between columns
+- Elements aligned to grid lines
+- Responsive breakpoint hints
+
+#### Sidebar + Main Layout
+
+**Visual Indicators:**
+
+- Narrow fixed-width column on left or right
+- Wider flexible main content area
+- Clear visual separation (border, background, or space)
+- Navigation elements typically in sidebar
+
+### Region Detection Heuristics
+
+**Header Detection:**
+
+- Located in top 15% of viewport
+- Full width or near-full width
+- Contains logo (top-left corner image)
+- Contains navigation elements
+- Typically 60-100px height
+
+**Navigation Detection:**
+
+- Sidebar: Left or right edge, narrow width (200-300px), full height
+- Top nav: Within header region, horizontal list of links
+- Contains repeated similar elements (nav items)
+
+**Main Content Detection:**
+
+- Largest contiguous content area
+- Excludes header, footer, sidebar regions
+- Contains primary content blocks
+
+**Footer Detection:**
+
+- Located in bottom 10-15% of viewport
+- Full width
+- Often darker background than main content
+- Contains links, copyright text, social icons
+
+### Layout Regions Reference
+
+| Region     | Visual Cues                                   | Typical Elements                       |
+| ---------- | --------------------------------------------- | -------------------------------------- |
+| Header     | Top position, full width, distinct background | Logo, navigation, search, auth buttons |
+| Navigation | Horizontal or vertical menu structure         | Links, icons, dropdowns                |
+| Hero       | Large top section, prominent heading          | Headline, CTA, image/illustration      |
+| Main       | Central content area                          | Primary page content                   |
+| Sidebar    | Narrow column, secondary info                 | Filters, navigation, widgets           |
+| Footer     | Bottom position, darker background            | Links, copyright, social icons         |
+
+### Grid System Detection
+
+**Step 1: Identify Container Width**
+
+- Look for consistent outer margins
+- Note if content is centered or full-bleed
+- Measure visual max-width
+
+**Step 2: Count Columns**
+
+- Align visible elements to potential column lines
+- Look for patterns: 12-col (Bootstrap), 4-col, 6-col
+- Check responsive behavior hints
+
+**Step 3: Measure Gutters**
+
+- Find consistent horizontal gaps between elements
+- Common values: 16px, 20px, 24px, 32px
+
+**Grid Calculation:**
+
+```
+Column Width = (Container Width - (Gaps * (Columns - 1))) / Columns
+Gutter Width = Gap between adjacent columns
+```
+
+### Flexbox vs Grid Indicators
+
+**Flexbox Indicators:**
+
+- Items of varying widths in same row
+- Items wrapping to next line
+- Single-axis alignment dominance
+- Unequal distribution of remaining space
+
+**Grid Indicators:**
+
+- Strict column alignment across rows
+- Items spanning multiple columns
+- Both row and column tracks visible
+- Consistent cell sizing
+
+---
+
+## Component Detection Patterns
+
+### Component Detection Decision Tree
+
+```
+Is it interactive?
+├── Yes → Does it trigger an action?
+│   ├── Yes → Button/Link/Icon Button
+│   └── No → Does it accept input?
+│       ├── Yes → Input/Select/Checkbox/Radio
+│       └── No → Toggle/Switch
+└── No → Is it a container?
+    ├── Yes → Card/Modal/Drawer/Section
+    └── No → Is it text?
+        ├── Yes → Heading/Paragraph/Label/Caption
+        └── No → Is it visual?
+            ├── Yes → Image/Icon/Avatar/Badge
+            └── No → Divider/Spacer
+```
+
+### Bounding Box Detection Heuristics
+
+**Visual Boundary Detection:**
+
+- Look for clear edges (borders, shadows, background changes)
+- Identify whitespace gaps that separate elements
+- Group elements by visual proximity (Gestalt proximity principle)
+- Consider alignment lines as grouping indicators
+
+### Common Component Signatures
+
+| Component Type | Visual Indicators                                                  |
+| -------------- | ------------------------------------------------------------------ |
+| Button         | Rounded rectangle, consistent height, centered text, possible icon |
+| Card           | Shadow, border-radius, contained content group, consistent padding |
+| Input          | Bordered rectangle, placeholder text, label above/beside           |
+| Navigation     | Horizontal or vertical list, evenly spaced items, highlight state  |
+| Avatar         | Circular or rounded-square image, typically 24-64px                |
+| Badge          | Small pill shape, high-contrast colors, near other elements        |
+| Modal          | Centered overlay, shadow, close button, dimmed background          |
+| Dropdown       | Text + chevron icon, bounded width                                 |
+| Table          | Grid of cells, header row, alternating row colors                  |
+
+### Button Detection
+
+**Visual Characteristics:**
+
+- Distinct background color (different from surroundings)
+- Rounded corners (border-radius > 0)
+- Centered text
+- Horizontal padding visible
+- Consistent height (32-48px typical)
+- Often contains icon + text or text only
+
+**Button Variants:**
+
+| Variant     | Background        | Border      | Text          |
+| ----------- | ----------------- | ----------- | ------------- |
+| Primary     | Solid brand color | None        | White/inverse |
+| Secondary   | Transparent/light | 1-2px solid | Brand color   |
+| Tertiary    | Transparent       | None        | Brand color   |
+| Ghost       | Transparent       | None        | Muted color   |
+| Destructive | Red/danger color  | None        | White         |
+
+### Input Field Detection
+
+**Visual Characteristics:**
+
+- Rectangular shape
+- Border visible (light gray typical)
+- Background (white or very light)
+- Placeholder text (muted color)
+- Height: 36-44px typical
+- Often has label above
+
+**Input Variants:**
+
+- Text input: Single line, cursor position
+- Textarea: Multi-line, taller
+- Select: Dropdown arrow icon on right
+- Checkbox: Square, small (16-20px)
+- Radio: Circle, small (16-20px)
+- Toggle/Switch: Pill shape, binary state indicator
+
+### Card Detection
+
+**Visual Characteristics:**
+
+- Distinct container boundary
+- Background different from page
+- Shadow or border creating separation
+- Contains multiple child elements
+- Consistent padding around content
+- Often in repeating grid patterns
+
+**Card Anatomy:**
+
+1. Image area (top, optional)
+2. Header/title
+3. Body content
+4. Footer/actions (optional)
+
+### Container Recognition Patterns
+
+**Flex Container Detection:**
+
+- Children aligned in single direction (row or column)
+- Consistent gap between children
+- Children may have different sizes
+- Look for: justify-content and align-items behavior
+
+**Grid Container Detection:**
+
+- Elements aligned in both rows and columns
+- Consistent column widths or repeated patterns
+- Gaps between grid cells
+- Often used for: card grids, image galleries, data tables
+
+---
+
+## Color Extraction Patterns
+
+### Systematic Color Sampling
+
+#### Background Colors (Priority Order)
+
+1. Page background (outermost)
+2. Section backgrounds (cards, modals)
+3. Component backgrounds (buttons, inputs)
+4. Hover/active state backgrounds
+
+#### Foreground Colors (Priority Order)
+
+1. Primary text (headings, body)
+2. Secondary text (captions, metadata)
+3. Muted/disabled text
+4. Link colors (default, hover, visited)
+5. Error/success/warning text
+
+#### Border and Divider Colors
+
+- Card borders
+- Input field borders (default, focus, error)
+- Divider lines
+- Table borders
+
+### Color Categorization System
+
+**Primary Palette:**
+
+- Primary: Main brand color, CTAs
+- Secondary: Supporting brand color
+- Accent: Highlight, emphasis
+
+**Neutral Palette:**
+
+- Background colors (lightest to darkest)
+- Text colors (body, muted, heading)
+- Border colors
+- Divider colors
+
+**Semantic Colors:**
+
+- Success: Typically green spectrum (hue 100-140)
+- Warning: Typically yellow/orange spectrum (hue 30-50)
+- Error/Danger: Typically red spectrum (hue 0-10, 350-360)
+- Info: Typically blue spectrum (hue 200-220)
+
+### Color Semantic Mapping Table
+
+| Visual Context    | Semantic Token Name               | Usage Description          |
+| ----------------- | --------------------------------- | -------------------------- |
+| Page background   | `color.background.default`        | Main page backdrop         |
+| Card surface      | `color.background.elevated`       | Raised containers          |
+| Primary button    | `color.interactive.primary`       | Main CTAs                  |
+| Button hover      | `color.interactive.primary-hover` | Primary button hover state |
+| Body text         | `color.foreground.default`        | Standard text content      |
+| Muted text        | `color.foreground.muted`          | Secondary information      |
+| Error indicator   | `color.feedback.error`            | Error states and messages  |
+| Success indicator | `color.feedback.success`          | Success confirmations      |
+| Warning indicator | `color.feedback.warning`          | Warning notices            |
+| Input border      | `color.border.input`              | Form field boundaries      |
+| Focus ring        | `color.border.focus`              | Keyboard focus indicators  |
+
+### Color Extraction Algorithm
+
+```
+1. Sample colors from each detected component
+2. Cluster similar colors (within delta-E threshold of ~3)
+3. Identify dominant colors by frequency
+4. Assign semantic meaning based on usage context:
+   - Large area backgrounds -> background tokens
+   - Text on backgrounds -> foreground tokens
+   - Small interactive elements -> interactive tokens
+   - Borders and lines -> border tokens
+```
+
+### Color Palette Extraction Steps
+
+1. Extract all unique colors
+2. Group similar colors (within deltaE 2.0)
+3. Sort each group by lightness
+4. Create scale (50, 100, 200, ... 900)
+5. Identify semantic roles
+
+---
+
+## Typography Extraction Patterns
+
+### Font Family Detection
+
+**Visual Analysis:**
+
+- Serif vs Sans-serif (look for feet/stems)
+- Monospace (equal character width)
+- Display/decorative fonts (headings only)
+
+**Common Font Signatures:**
+
+| Font            | Visual Identifier                        |
+| --------------- | ---------------------------------------- |
+| Inter           | Clean sans-serif, slight humanist curves |
+| Roboto          | Geometric with open counters             |
+| SF Pro          | Apple system font, compact               |
+| Helvetica       | Classic, uniform stroke width            |
+| Georgia         | Serif with modern proportions            |
+| Source Code Pro | Monospace, distinct 0 and O              |
+
+**Common Font Stacks:**
+
+- System: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto
+- Sans-serif: Inter, Helvetica Neue, Arial
+- Serif: Georgia, "Times New Roman", serif
+- Mono: "SF Mono", Monaco, Consolas, monospace
+
+### Type Scale Detection
+
+**Common Scale Ratios:**
+
+| Ratio | Name             | Example Scale      |
+| ----- | ---------------- | ------------------ |
+| 1.067 | Minor Second     | 16, 17, 18, 19, 21 |
+| 1.125 | Major Second     | 16, 18, 20, 23, 26 |
+| 1.200 | Minor Third      | 16, 19, 23, 28, 33 |
+| 1.250 | Major Third      | 16, 20, 25, 31, 39 |
+| 1.333 | Perfect Fourth   | 16, 21, 28, 38, 50 |
+| 1.414 | Augmented Fourth | 16, 23, 32, 45, 64 |
+| 1.500 | Perfect Fifth    | 16, 24, 36, 54, 81 |
+
+**Detection Algorithm:**
+
+1. Collect all font sizes
+2. Sort ascending
+3. Calculate ratios between consecutive sizes
+4. Find most common ratio
+5. Match to standard scale
+
+### Text Style Hierarchy
+
+**Typical Hierarchy:**
+
+| Level      | Usage              | Size Range | Weight          |
+| ---------- | ------------------ | ---------- | --------------- |
+| Display    | Hero headlines     | 48-72px    | Bold/Black      |
+| H1         | Page titles        | 32-48px    | Bold            |
+| H2         | Section headers    | 24-32px    | Semibold        |
+| H3         | Subsection headers | 20-24px    | Semibold        |
+| H4         | Card titles        | 18-20px    | Medium          |
+| Body Large | Lead paragraphs    | 18-20px    | Regular         |
+| Body       | Standard text      | 14-16px    | Regular         |
+| Body Small | Captions           | 12-14px    | Regular         |
+| Caption    | Metadata           | 10-12px    | Regular         |
+| Label      | Form labels        | 12-14px    | Medium          |
+| Button     | Button text        | 14-16px    | Medium/Semibold |
+
+### Line Height Patterns
+
+| Use Case          | Line Height |
+| ----------------- | ----------- |
+| Headings          | 1.1 - 1.3   |
+| Body text         | 1.4 - 1.6   |
+| UI elements       | 1.0 - 1.2   |
+| Long-form reading | 1.6 - 1.8   |
+
+### Font Weight Detection
+
+- Thin/Light: 100-300 (barely visible stroke)
+- Normal/Regular: 400 (standard body text)
+- Medium: 500 (slightly emphasized)
+- Semibold: 600 (subheadings)
+- Bold: 700 (headings, emphasis)
+- Black: 800-900 (display text)
+
+---
+
+## Spacing and Dimensions Patterns
+
+### Base Unit Detection Algorithm
+
+1. Measure all gaps between elements
+2. Find Greatest Common Divisor (GCD)
+3. Validate GCD is reasonable (4px or 8px typical)
+4. Build scale from base unit
+
+**Common Base Units:**
+
+- 4px system: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64
+- 8px system: 8, 16, 24, 32, 40, 48, 64, 80, 96
+
+### Spacing Scale Reference
+
+**4px Base Scale (Tailwind-style):**
+
+```
+0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96
+```
+
+**8px Base Scale:**
+
+```
+0, 8, 16, 24, 32, 48, 64, 96, 128
+```
+
+### Padding vs Margin Detection
+
+**Padding (Internal Spacing):**
+
+- Distance from container edge to content
+- Consistent within component types
+- Often symmetric (same top/bottom, left/right)
+
+**Margin (External Spacing):**
+
+- Distance between components
+- May vary by context
+- Often uses larger values than padding
+
+### Component Spacing Patterns
+
+| Component | Padding X | Padding Y | Gap  |
+| --------- | --------- | --------- | ---- |
+| Button SM | 12px      | 6px       | 8px  |
+| Button MD | 16px      | 8px       | 8px  |
+| Button LG | 24px      | 12px      | 12px |
+| Card      | 24px      | 24px      | 16px |
+| Input     | 12px      | 8px       | -    |
+| Modal     | 32px      | 24px      | 24px |
+
+### Spacing Relationship Map
+
+```
+Component Internal Padding: spacing-sm to spacing-md (8-16px)
+Component Gap (siblings): spacing-md to spacing-lg (16-24px)
+Section Gap: spacing-xl to spacing-2xl (32-64px)
+Page Margins: spacing-lg to spacing-xl (24-48px)
+```
+
+### Dimension Tokens
+
+**Container Widths:**
+
+- Full width: 100% of viewport
+- Constrained: Common max-widths (1024px, 1200px, 1440px)
+- Content width: Typical 600-800px for readability
+
+**Component Sizing:**
+
+| Component     | SM   | MD   | LG   |
+| ------------- | ---- | ---- | ---- |
+| Button Height | 32px | 40px | 48px |
+| Input Height  | 32px | 40px | 48px |
+| Icon Size     | 16px | 20px | 24px |
+| Avatar        | 32px | 40px | 48px |
+
+---
+
+## State Inference Rules
+
+### Interactive States
+
+| State          | Visual Indicators                        |
+| -------------- | ---------------------------------------- |
+| Default        | Base appearance                          |
+| Hover          | Slight color change, cursor pointer      |
+| Active/Pressed | Darker shade, slight scale reduction     |
+| Focus          | Visible ring/outline, increased contrast |
+| Disabled       | Muted colors, reduced opacity            |
+| Loading        | Spinner, skeleton, pulsing               |
+| Error          | Red borders/text, error icon             |
+| Success        | Green indicators, checkmark              |
+
+### Button States Inference
+
+**From Static Screenshot:**
+
+- Default: Base styling visible
+- Hover: Infer +10% darker background, elevated shadow
+- Active: Infer +20% darker, no shadow, slight scale down
+- Focus: Infer focus ring (2px outline, offset 2px)
+- Disabled: Infer reduced opacity (0.5-0.6), muted colors
+
+**When Multiple States Visible:**
+
+- Different buttons may show different states
+- Look for visual variations in similar components
+- Catalog each variation as a state
+
+### Input States Inference
+
+- Default: Standard border color
+- Hover: Slightly darker border
+- Focus: Primary color border, focus ring
+- Filled: Content present, potentially different label position
+- Error: Red/danger border, error message below
+- Disabled: Gray background, muted text
+
+### Interactive Feedback Patterns
+
+| State    | Background | Border     | Shadow  | Transform   |
+| -------- | ---------- | ---------- | ------- | ----------- |
+| Default  | Base       | Base       | Level 1 | none        |
+| Hover    | Darken 5%  | Darken 10% | Level 2 | none        |
+| Active   | Darken 10% | Darken 15% | none    | scale(0.98) |
+| Focus    | Base       | Primary    | Base    | none        |
+| Disabled | Gray 200   | Gray 300   | none    | none        |
+
+---
+
+## Accessibility Analysis Patterns
+
+### Contrast Ratio Requirements
+
+**WCAG 2.1 Requirements:**
+
+| Level | Normal Text | Large Text | UI Components |
+| ----- | ----------- | ---------- | ------------- |
+| AA    | 4.5:1       | 3:1        | 3:1           |
+| AAA   | 7:1         | 4.5:1      | 4.5:1         |
+
+Large text defined as: >= 18pt (24px) or >= 14pt bold (19px)
+
+**Contrast Calculation Formula:**
+
+```
+L = 0.2126 * R + 0.7152 * G + 0.0722 * B (relative luminance)
+Contrast Ratio = (L1 + 0.05) / (L2 + 0.05)
+where L1 > L2
+```
+
+### Touch Target Analysis
+
+**Minimum Size Requirements:**
+
+| Standard         | Size                               |
+| ---------------- | ---------------------------------- |
+| WCAG 2.5.5 (AAA) | 44x44 CSS pixels                   |
+| WCAG 2.5.8 (AA)  | 24x24 CSS pixels with spacing      |
+| iOS HIG          | 44x44 points                       |
+| Material Design  | 48x48dp (with 8dp spacing minimum) |
+
+**Detection Approach:**
+
+1. Identify interactive elements (buttons, links, inputs)
+2. Measure bounding box dimensions
+3. Check spacing between adjacent touch targets
+4. Flag elements below minimum thresholds
+
+### Semantic Structure Analysis
+
+**Expected Semantic Roles:**
+
+| Element      | Role                        | Usage                |
+| ------------ | --------------------------- | -------------------- |
+| Navigation   | nav, role="navigation"      | Main navigation      |
+| Main Content | main, role="main"           | Primary content      |
+| Header       | header, role="banner"       | Page header          |
+| Footer       | footer, role="contentinfo"  | Page footer          |
+| Sidebar      | aside, role="complementary" | Secondary content    |
+| Search       | role="search"               | Search functionality |
+| Form         | form, role="form"           | Form container       |
+| Button       | button, role="button"       | Interactive action   |
+| Link         | a, role="link"              | Navigation link      |
+
+### Color Blindness Considerations
+
+**Types and Prevalence:**
+
+- Protanopia (red-blind): 1% of males
+- Deuteranopia (green-blind): 1% of males
+- Tritanopia (blue-blind): <0.01%
+
+**Critical Rule:** Color must not be the only visual means of conveying information (WCAG 1.4.1)
+
+**Check For:**
+
+- Information conveyed only by color
+- Error states without icon/text
+- Status without additional indicators
+- Charts/graphs without patterns
+
+---
+
+## Component Classification Taxonomy
+
+### Atomic Components (Atoms)
+
+**Text Elements:**
+
+- `heading`: h1-h6 equivalent
+- `paragraph`: Body text blocks
+- `caption`: Small descriptive text
+- `label`: Form labels, UI labels
+- `badge`: Small status indicators
+- `tag`: Categorization chips
+
+**Interactive Elements:**
+
+- `button`: Primary action trigger
+- `icon-button`: Icon-only button
+- `link`: Navigation link
+- `checkbox`: Binary selection
+- `radio`: Single selection from group
+- `switch`: Toggle control
+- `input`: Text input field
+- `textarea`: Multi-line input
+- `select`: Dropdown selection
+- `slider`: Range selection
+
+**Media Elements:**
+
+- `image`: Static images
+- `avatar`: User/entity images
+- `icon`: Symbolic graphics
+- `logo`: Brand marks
+- `video`: Video players
+
+**Feedback Elements:**
+
+- `spinner`: Loading indicator
+- `progress`: Progress bar
+- `skeleton`: Loading placeholder
+- `alert`: Inline feedback
+- `toast`: Temporary notification
+
+### Molecular Components (Molecules)
+
+- `form-field`: Label + input + helper
+- `search-bar`: Input + icon + button
+- `nav-item`: Icon + text + indicator
+- `breadcrumb`: Path navigation
+- `menu-item`: Icon + text + shortcut
+- `list-item`: Content + actions
+
+### Organism Components (Organisms)
+
+**Layout Components:**
+
+- `header`: Page header
+- `navigation`: Nav container
+- `sidebar`: Side navigation
+- `footer`: Page footer
+- `card`: Bounded content group
+- `modal`: Dialog overlay
+- `drawer`: Slide-in panel
+
+**Content Components:**
+
+- `hero`: Hero section
+- `feature-section`: Feature list
+- `testimonial`: User testimonial
+- `pricing-table`: Pricing comparison
+- `data-table`: Tabular data
+- `form`: Form container
+
+### Component Naming Conventions
+
+**Hierarchical Naming:**
+
+```
+{category}-{type}-{variant}
+
+Examples:
+- button-primary
+- button-secondary
+- button-ghost
+- input-text
+- input-password
+- card-product
+- card-user
+- nav-horizontal
+- nav-vertical
+```
+
+**State-Aware Naming:**
+
+```
+{component}-{state}
+
+Examples:
+- button-hover
+- button-active
+- button-disabled
+- input-focus
+- input-error
+- card-selected
+```
+
+---
+
+## Confidence Scoring
+
+### Per-Category Confidence Levels
+
+**High Confidence (0.8-1.0):**
+
+- Clear, high-resolution input
+- Standard design patterns
+- Consistent styling throughout
+- Multiple examples of each element type
+
+**Medium Confidence (0.5-0.79):**
+
+- Some ambiguity in element boundaries
+- Mix of standard and custom patterns
+- Minor inconsistencies
+- Limited examples of some elements
+
+**Low Confidence (0.0-0.49):**
+
+- Low resolution or artifacts
+- Highly custom/unusual design
+- Significant inconsistencies
+- Minimal examples to pattern match
+
+### Confidence Factors (Weighted)
+
+| Factor        | Weight | Description                           |
+| ------------- | ------ | ------------------------------------- |
+| Resolution    | 0.20   | Image quality and clarity             |
+| Consistency   | 0.25   | Design system coherence               |
+| Coverage      | 0.20   | % of elements successfully identified |
+| Pattern Match | 0.20   | Alignment with known patterns         |
+| Completeness  | 0.15   | All token categories populated        |
+
+### Confidence Reporting Format
+
+```json
+{
+  "$extensions": {
+    "com.design-spec.confidence": {
+      "overall": 0.85,
+      "byCategory": {
+        "layout": 0.9,
+        "components": 0.8,
+        "colors": 0.95,
+        "typography": 0.75,
+        "spacing": 0.85,
+        "states": 0.7
+      },
+      "notes": [
+        "Typography font family inferred from visual characteristics",
+        "Button hover states not visible, using standard inference"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Output Format Conversions
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Colors */
+  --color-primary: #3b82f6;
+  --color-secondary: #6366f1;
+  --color-text-primary: #1f2937;
+
+  /* Typography */
+  --font-family-primary: "Inter", system-ui, sans-serif;
+  --font-size-base: 16px;
+  --font-weight-medium: 500;
+  --line-height-normal: 1.5;
+
+  /* Spacing */
+  --spacing-1: 4px;
+  --spacing-2: 8px;
+  --spacing-4: 16px;
+
+  /* Border Radius */
+  --radius-md: 8px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+}
+```
+
+### SCSS Variables
+
+```scss
+// Colors
+$color-primary: #3b82f6;
+$color-secondary: #6366f1;
+
+// Typography
+$font-family-primary: "Inter", system-ui, sans-serif;
+$font-sizes: (
+  "xs": 12px,
+  "sm": 14px,
+  "base": 16px,
+  "lg": 18px,
+);
+
+// Spacing
+$spacing-scale: (
+  1: 4px,
+  2: 8px,
+  3: 12px,
+  4: 16px,
+);
+```
+
+### Tailwind Config
+
+```javascript
+module.exports = {
+  theme: {
+    colors: {
+      primary: {
+        DEFAULT: "#3B82F6",
+        dark: "#2563EB",
+        light: "#60A5FA",
+      },
+    },
+    fontFamily: {
+      sans: ["Inter", "system-ui", "sans-serif"],
+    },
+    fontSize: {
+      xs: "12px",
+      sm: "14px",
+      base: "16px",
+    },
+    spacing: {
+      1: "4px",
+      2: "8px",
+      4: "16px",
+    },
+    borderRadius: {
+      sm: "4px",
+      md: "8px",
+      lg: "12px",
+    },
+  },
+};
+```
+
+### Style Dictionary Format
+
+```json
+{
+  "color": {
+    "primary": { "value": "#3B82F6" },
+    "secondary": { "value": "#6366F1" }
+  },
+  "font": {
+    "family": {
+      "primary": { "value": "Inter, system-ui, sans-serif" }
+    },
+    "size": {
+      "base": { "value": "16px" }
+    }
+  }
+}
+```
+
+### Figma Variables JSON
+
+```json
+{
+  "colors/primary": {
+    "type": "COLOR",
+    "value": "#3B82F6",
+    "scopes": ["ALL_SCOPES"]
+  },
+  "spacing/md": {
+    "type": "FLOAT",
+    "value": 16,
+    "scopes": ["GAP", "WIDTH_HEIGHT"]
+  }
+}
+```
+
+---
+
+## Validation Checklist
+
+### Token Extraction
+
+- [ ] All colors captured with hex/RGB values
+- [ ] Font families identified accurately
+- [ ] Font sizes mapped to scale
+- [ ] Spacing values follow consistent scale
+- [ ] Border radii captured
+- [ ] Shadow values captured (offset, blur, spread, color)
+
+### Component Tree
+
+- [ ] All visible components identified
+- [ ] Correct parent-child relationships
+- [ ] Appropriate atomic level assigned
+- [ ] Bounding boxes accurate
+- [ ] States and variants noted
+
+### Accessibility
+
+- [ ] Contrast ratios checked
+- [ ] Heading hierarchy validated
+- [ ] Interactive elements identified
+- [ ] Focus indicators noted
+- [ ] Semantic landmarks mapped
+
+### Layout
+
+- [ ] Grid system detected
+- [ ] Major regions identified
+- [ ] Spacing patterns recognized
+- [ ] Responsive hints captured
+
+---
+
+## Best Practices Summary
+
+### For Accurate Extraction
+
+1. **Start with layout** - Understand the structure before details
+2. **Use reference points** - Identify repeating patterns as calibration
+3. **Cross-validate** - Compare findings across passes
+4. **Document uncertainty** - Mark low-confidence areas
+5. **Preserve relationships** - Maintain token references, don't flatten
+
+### For AI-Readable Output
+
+1. **Semantic naming** - Use intent-based names (color.interactive.primary)
+2. **Rich descriptions** - Add $description explaining when/how to use
+3. **Explicit relationships** - Document token pairings and dependencies
+4. **Component mapping** - Show which tokens apply to which components
+5. **Usage examples** - Include context for complex tokens
+
+### For Developer Handoff
+
+1. **Complete tokens** - Include all variations needed for implementation
+2. **Clear hierarchy** - Organize logically (primitive -> semantic -> component)
+3. **State coverage** - Document all interactive states
+4. **Responsive values** - Note breakpoint variations if detected
+5. **Accessibility notes** - Include WCAG compliance information