diff --git a/docs/design-system/README.md b/docs/design-system/README.md new file mode 100644 index 0000000..8f7ed59 --- /dev/null +++ b/docs/design-system/README.md @@ -0,0 +1,162 @@ +# Design System Audit Documentation + +## Overview + +This directory contains comprehensive documentation for auditing design system compliance across all components in the Frontend Recipeer application. The audit framework ensures consistency, accessibility, and maintainability of our atomic design-based component system. + +## Quick Start + +1. **Review the [Audit Criteria](./audit-criteria.md)** to understand evaluation standards +2. **Familiarize yourself with the [Scoring Methodology](./scoring-methodology.md)** for consistent evaluation +3. **Download the [Component Tracking Template](./component-audit-template.csv)** to track audit progress +4. **Use the [Audit Report Template](./audit-report-template.md)** to document findings +5. **Reference the [Accessibility Checklist](./accessibility-checklist.md)** for WCAG 2.1 AA compliance + +## Documentation Structure + +### Core Documents + +| Document | Purpose | Audience | +|----------|---------|----------| +| [Audit Criteria](./audit-criteria.md) | Defines scoring system and evaluation areas | All team members | +| [Scoring Methodology](./scoring-methodology.md) | Detailed instructions for consistent scoring | Auditors | +| [Accessibility Checklist](./accessibility-checklist.md) | WCAG 2.1 AA compliance requirements | Developers, Auditors | +| [Component Tracking Template](./component-audit-template.csv) | Spreadsheet for tracking audit progress | Project managers, Auditors | +| [Audit Report Template](./audit-report-template.md) | Standardized reporting format | Auditors, Stakeholders | + +### Supporting Documents + +| Document | Purpose | +|----------|---------| +| [ADR-0001: Atomic Design Component Architecture](../adr/0001-atomic-design-component-architecture.md) | Foundation architectural decisions | +| [ADR-001: Adopt Atomic Design + Component-Driven Development](../adr/001-atomic-design-architecture.md) | Implementation details and validation | +| [Example: Button Component Audit](./example-button-audit.md) | Demonstration of audit methodology in practice | + +## Audit Framework + +### Evaluation Areas (100 points total) + +1. **Design Token Compliance** (25 points) + - Color usage and theme integration + - Typography scale adherence + - Spacing consistency + +2. **Visual Consistency** (25 points) + - Component variants and states + - Layout patterns and responsive design + - Visual hierarchy + +3. **Accessibility Compliance** (25 points) + - WCAG 2.1 AA requirements + - Keyboard navigation and screen reader support + - Interactive accessibility + +4. **Theme Support** (15 points) + - Light/dark mode adaptation + - System theme detection + +5. **Documentation Quality** (10 points) + - Storybook documentation completeness + - Code documentation and examples + +### Component Priority Levels + +- **Critical (90+ score required)**: Foundational atoms (Button, Input, Typography) +- **High (80+ score required)**: Key molecules and organisms (QuantityAdjuster, RecipeCard) +- **Medium (70+ score required)**: Complex organisms and templates +- **Low (60+ score required)**: Experimental or legacy components + +## Audit Process + +### 1. Planning Phase +- [ ] Identify components for audit using priority levels +- [ ] Assign auditors and schedule audit dates +- [ ] Set up tracking system using component template + +### 2. Evaluation Phase +- [ ] Score components using detailed criteria +- [ ] Document findings with evidence +- [ ] Identify issues and improvement opportunities + +### 3. Reporting Phase +- [ ] Complete audit reports using standard template +- [ ] Prioritize issues by severity +- [ ] Create actionable improvement plans + +### 4. Remediation Phase +- [ ] Address critical and major issues +- [ ] Re-audit improved components +- [ ] Update tracking system with results + +### 5. Continuous Improvement +- [ ] Schedule regular re-audits +- [ ] Update criteria based on learnings +- [ ] Share best practices across team + +## Getting Started with Audits + +### For New Auditors + +1. **Read the documentation**: Start with audit criteria and scoring methodology +2. **Review the example audit**: Study the [Button component audit example](./example-button-audit.md) to understand the process +3. **Practice scoring**: Audit a simple atom component to understand the process +4. **Shadow experienced auditor**: Observe an audit session for complex components +5. **Start with low-risk audits**: Begin with non-critical components + +### For Component Developers + +1. **Understand the criteria**: Review audit standards before building components +2. **Use the accessibility checklist**: Ensure WCAG compliance during development +3. **Test across themes**: Verify light/dark mode support +4. **Document thoroughly**: Create comprehensive Storybook stories +5. **Self-audit before submission**: Use the criteria to review your own work + +## Tools and Resources + +### Required Tools +- **Storybook**: Component documentation and visual testing +- **Browser DevTools**: Accessibility and contrast checking +- **axe DevTools**: Automated accessibility testing +- **Screen reader software**: Manual accessibility testing + +### Recommended Tools +- **WAVE**: Web accessibility evaluation +- **Lighthouse**: Performance and accessibility auditing +- **Color contrast analyzers**: Ensuring WCAG compliance +- **Figma**: Design comparison and measurement + +### Learning Resources +- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/) +- [Atomic Design Methodology](https://atomicdesign.bradfrost.com/) +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) + +## Quality Assurance + +### Audit Consistency +- Multiple auditors should review high-priority components +- Regular calibration sessions to maintain scoring consistency +- Cross-validation of audit results for critical components + +### Continuous Improvement +- Quarterly review of audit criteria and methodology +- Integration of new accessibility requirements +- Update processes based on team feedback and industry best practices + +## Support and Questions + +### Getting Help +- Review the detailed [Scoring Methodology](./scoring-methodology.md) for specific guidance +- Consult the [Accessibility Checklist](./accessibility-checklist.md) for WCAG questions +- Reach out to the design system team for clarification + +### Feedback and Improvements +- Submit issues or suggestions for improving the audit process +- Propose updates to criteria based on new requirements +- Share learnings from audit experiences with the team + +--- + +**Last Updated**: 2024-12-29 +**Version**: 1.0 +**Maintained by**: Design System Team \ No newline at end of file diff --git a/docs/design-system/accessibility-checklist.md b/docs/design-system/accessibility-checklist.md new file mode 100644 index 0000000..1e3814d --- /dev/null +++ b/docs/design-system/accessibility-checklist.md @@ -0,0 +1,332 @@ +# Accessibility Compliance Checklist (WCAG 2.1 AA) + +## Overview + +This checklist ensures components meet Web Content Accessibility Guidelines (WCAG) 2.1 Level AA standards. Each component should be evaluated against these criteria during design system audits. + +## Principle 1: Perceivable + +### 1.1 Text Alternatives +- [ ] **1.1.1 Non-text Content (A)**: All images, icons, and non-text content have appropriate alternative text + - [ ] Decorative images use empty alt attributes (`alt=""`) + - [ ] Functional images have descriptive alt text + - [ ] Icons have accessible names via aria-label or sr-only text + - [ ] Complex images have detailed descriptions + +### 1.2 Time-based Media +- [ ] **1.2.1 Audio-only and Video-only (A)**: Pre-recorded audio and video have alternatives +- [ ] **1.2.2 Captions (A)**: Live and pre-recorded video have captions +- [ ] **1.2.3 Audio Description (A)**: Pre-recorded video has audio descriptions +- [ ] **1.2.4 Captions (Live) (AA)**: Live audio content has captions +- [ ] **1.2.5 Audio Description (AA)**: Pre-recorded video has comprehensive audio descriptions + +### 1.3 Adaptable +- [ ] **1.3.1 Info and Relationships (A)**: Information and relationships are programmatically determinable + - [ ] Headings use proper heading tags (h1-h6) + - [ ] Lists use proper list markup (ul, ol, li) + - [ ] Tables use proper table markup with headers + - [ ] Form labels are associated with their controls + - [ ] Related form controls are grouped with fieldset/legend + +- [ ] **1.3.2 Meaningful Sequence (A)**: Content order is logical when linearized + - [ ] Tab order follows visual order + - [ ] Reading order makes sense with CSS disabled + - [ ] Focus order is logical and predictable + +- [ ] **1.3.3 Sensory Characteristics (A)**: Instructions don't rely solely on sensory characteristics + - [ ] Don't rely only on color to convey information + - [ ] Don't rely only on shape, size, position, or sound + - [ ] Provide text alternatives for visual cues + +- [ ] **1.3.4 Orientation (AA)**: Content is not restricted to single orientation + - [ ] Component works in both portrait and landscape + - [ ] No orientation restrictions unless essential + +- [ ] **1.3.5 Identify Input Purpose (AA)**: Input purpose can be programmatically determined + - [ ] Form inputs use appropriate autocomplete attributes + - [ ] Input types match their purpose (email, tel, url, etc.) + +### 1.4 Distinguishable +- [ ] **1.4.1 Use of Color (A)**: Color is not the only way to convey information + - [ ] Error states use icons or text in addition to color + - [ ] Status indicators have textual or iconic alternatives + - [ ] Interactive elements have non-color indicators + +- [ ] **1.4.2 Audio Control (A)**: Auto-playing audio can be controlled + - [ ] Audio that plays for >3 seconds has controls + - [ ] Users can pause, stop, or control volume + +- [ ] **1.4.3 Contrast (Minimum) (AA)**: Text has sufficient contrast + - [ ] Normal text: 4.5:1 contrast ratio minimum + - [ ] Large text (18pt+/14pt+ bold): 3:1 contrast ratio minimum + - [ ] Text on images meets contrast requirements + - [ ] Both light and dark themes meet requirements + +- [ ] **1.4.4 Resize Text (AA)**: Text can be resized up to 200% without assistive technology + - [ ] Text remains readable when zoomed to 200% + - [ ] No horizontal scrolling at 200% zoom + - [ ] All functionality remains available + +- [ ] **1.4.5 Images of Text (AA)**: Text is used instead of images of text when possible + - [ ] No images of text unless customizable or essential + - [ ] CSS text styling preferred over text images + +- [ ] **1.4.10 Reflow (AA)**: Content reflows at 320px width without horizontal scrolling + - [ ] Component adapts to narrow viewports + - [ ] No horizontal scrolling required + - [ ] All content and functionality available + +- [ ] **1.4.11 Non-text Contrast (AA)**: UI components have sufficient contrast + - [ ] Interactive elements: 3:1 contrast ratio + - [ ] Focus indicators: 3:1 contrast ratio + - [ ] Graphical elements: 3:1 contrast ratio + +- [ ] **1.4.12 Text Spacing (AA)**: Text spacing can be adjusted without loss of functionality + - [ ] Line height adjustable to 1.5 times font size + - [ ] Paragraph spacing adjustable to 2 times font size + - [ ] Letter spacing adjustable to 0.12 times font size + - [ ] Word spacing adjustable to 0.16 times font size + +- [ ] **1.4.13 Content on Hover or Focus (AA)**: Additional content on hover/focus is controllable + - [ ] Hoverable: Additional content can be hovered + - [ ] Dismissible: Content can be dismissed without moving pointer + - [ ] Persistent: Content remains visible until dismissed or no longer valid + +## Principle 2: Operable + +### 2.1 Keyboard Accessible +- [ ] **2.1.1 Keyboard (A)**: All functionality available via keyboard + - [ ] All interactive elements can be reached with Tab + - [ ] All interactive elements can be activated with Enter or Space + - [ ] Custom components support keyboard interaction + - [ ] No keyboard traps (except modal dialogs) + +- [ ] **2.1.2 No Keyboard Trap (A)**: Keyboard focus can be moved away from component + - [ ] Focus can be moved out of component using standard navigation + - [ ] Modal dialogs implement proper focus trapping with escape routes + - [ ] Focus returns to appropriate element when trap is released + +- [ ] **2.1.4 Character Key Shortcuts (A)**: Single character shortcuts can be disabled or remapped + - [ ] Single key shortcuts are avoided or configurable + - [ ] Shortcuts only active when relevant component has focus + +### 2.2 Enough Time +- [ ] **2.2.1 Timing Adjustable (A)**: Time limits can be extended or disabled + - [ ] No automatic timeouts unless essential + - [ ] Users can extend time limits + - [ ] Users warned before timeout expires + +- [ ] **2.2.2 Pause, Stop, Hide (A)**: Moving, blinking, or auto-updating content can be controlled + - [ ] Auto-playing content can be paused + - [ ] Auto-updating content can be controlled + - [ ] Blinking/moving content can be stopped + +### 2.3 Seizures and Physical Reactions +- [ ] **2.3.1 Three Flashes or Below Threshold (A)**: No content flashes more than 3 times per second + - [ ] No rapid flashing content + - [ ] Animations respect prefers-reduced-motion + - [ ] Flashing content below threshold or avoids red + +### 2.4 Navigable +- [ ] **2.4.1 Bypass Blocks (A)**: Skip links or other bypass mechanisms provided + - [ ] Skip navigation links where appropriate + - [ ] Proper heading structure for navigation + - [ ] Landmark regions defined + +- [ ] **2.4.2 Page Titled (A)**: Pages have descriptive titles + - [ ] Page titles describe content or purpose + - [ ] Dynamic content updates page title appropriately + +- [ ] **2.4.3 Focus Order (A)**: Focus order preserves meaning and operability + - [ ] Tab order follows logical sequence + - [ ] Focus moves predictably through interface + - [ ] Related elements are grouped in tab order + +- [ ] **2.4.4 Link Purpose (A)**: Link purpose can be determined from link text or context + - [ ] Links have descriptive text + - [ ] Generic text like "click here" avoided + - [ ] Context makes link purpose clear + +- [ ] **2.4.5 Multiple Ways (AA)**: Multiple ways to locate content within a site + - [ ] Navigation menus provided + - [ ] Search functionality available + - [ ] Site map or other wayfinding tools + +- [ ] **2.4.6 Headings and Labels (AA)**: Headings and labels describe topic or purpose + - [ ] Form labels clearly describe required input + - [ ] Headings accurately describe content sections + - [ ] Button text describes action clearly + +- [ ] **2.4.7 Focus Visible (AA)**: Focus indicator is visible + - [ ] All focusable elements have visible focus indicators + - [ ] Focus indicators have sufficient contrast + - [ ] Focus indicators are not obscured by other content + +### 2.5 Input Modalities +- [ ] **2.5.1 Pointer Gestures (A)**: Multi-point or path-based gestures have alternatives + - [ ] Complex gestures have simple alternatives + - [ ] Functionality doesn't require multi-point contact + +- [ ] **2.5.2 Pointer Cancellation (A)**: Functions triggered by single-pointer can be cancelled + - [ ] Down-event doesn't trigger function completion + - [ ] Up-event completes function with option to abort + - [ ] Essential functions clearly identified + +- [ ] **2.5.3 Label in Name (A)**: Accessible name contains visible label text + - [ ] Accessible name matches or includes visible label + - [ ] Speech recognition users can activate controls by visible name + +- [ ] **2.5.4 Motion Actuation (A)**: Functions triggered by motion can be disabled + - [ ] Motion-triggered functions have alternatives + - [ ] Users can disable motion activation + +## Principle 3: Understandable + +### 3.1 Readable +- [ ] **3.1.1 Language of Page (A)**: Primary language is programmatically determinable + - [ ] HTML lang attribute set appropriately + - [ ] Language changes marked with lang attribute + +- [ ] **3.1.2 Language of Parts (AA)**: Language of passages or phrases can be determined + - [ ] Foreign language content has lang attribute + - [ ] Proper names and technical terms handled appropriately + +### 3.2 Predictable +- [ ] **3.2.1 On Focus (A)**: Focus doesn't trigger unexpected context changes + - [ ] Receiving focus doesn't automatically change context + - [ ] Focus changes are predictable and expected + +- [ ] **3.2.2 On Input (A)**: Input doesn't trigger unexpected context changes + - [ ] Changing settings doesn't automatically submit forms + - [ ] Context changes are initiated by explicit user action + +- [ ] **3.2.3 Consistent Navigation (AA)**: Navigation is consistent across pages + - [ ] Navigation components appear in same relative order + - [ ] Consistent navigation patterns throughout application + +- [ ] **3.2.4 Consistent Identification (AA)**: Components with same functionality identified consistently + - [ ] Icons have consistent meaning throughout + - [ ] Buttons with same function have same labels + - [ ] Form elements consistently identified + +### 3.3 Input Assistance +- [ ] **3.3.1 Error Identification (A)**: Errors are identified and described to user + - [ ] Form errors clearly identified + - [ ] Error descriptions provided in text + - [ ] Invalid fields clearly marked + +- [ ] **3.3.2 Labels or Instructions (A)**: Labels or instructions provided for user input + - [ ] All form fields have labels + - [ ] Required fields clearly marked + - [ ] Input format instructions provided + +- [ ] **3.3.3 Error Suggestion (AA)**: Error correction suggestions provided when possible + - [ ] Specific error correction suggestions offered + - [ ] Suggestions don't compromise security + - [ ] Clear guidance for fixing errors + +- [ ] **3.3.4 Error Prevention (AA)**: Errors are prevented for legal, financial, or data modification submissions + - [ ] Submissions can be reversed, checked, or confirmed + - [ ] Important actions require confirmation + - [ ] Form validation prevents submission errors + +## Principle 4: Robust + +### 4.1 Compatible +- [ ] **4.1.1 Parsing (A)**: Markup is valid and well-formed + - [ ] HTML validates according to specifications + - [ ] Elements have complete start and end tags + - [ ] No duplicate attributes or IDs + - [ ] Elements properly nested + +- [ ] **4.1.2 Name, Role, Value (A)**: Name, role, and value can be programmatically determined + - [ ] Custom components have appropriate ARIA roles + - [ ] All form controls have accessible names + - [ ] State changes communicated to assistive technologies + - [ ] Values and properties programmatically determinable + +- [ ] **4.1.3 Status Messages (AA)**: Status messages can be programmatically determined + - [ ] Success messages announced to screen readers + - [ ] Error messages announced appropriately + - [ ] Progress updates communicated to assistive technologies + - [ ] Dynamic content changes announced + +## Component-Specific Checks + +### Forms +- [ ] All inputs have associated labels +- [ ] Required fields marked with required attribute and visual indicator +- [ ] Error messages associated with relevant fields +- [ ] Fieldsets group related inputs with descriptive legends +- [ ] Form validation provides clear, actionable feedback + +### Interactive Elements +- [ ] Buttons have descriptive text or aria-label +- [ ] Links clearly indicate their purpose and destination +- [ ] Interactive elements have minimum 44x44px touch target +- [ ] State changes (expanded, selected, etc.) communicated to assistive technologies + +### Dynamic Content +- [ ] Live regions announce important updates +- [ ] Loading states announced to screen readers +- [ ] Dynamic content changes don't disrupt user flow +- [ ] Focus management during content updates + +### Navigation +- [ ] Skip links provided for main content areas +- [ ] Breadcrumbs use proper markup and ARIA +- [ ] Current page/section clearly indicated +- [ ] Navigation landmarks properly defined + +## Testing Methods + +### Manual Testing +- [ ] Keyboard-only navigation testing +- [ ] Screen reader testing (NVDA, VoiceOver, JAWS) +- [ ] High contrast mode testing +- [ ] Zoom testing up to 200% +- [ ] Mobile accessibility testing + +### Automated Testing +- [ ] axe-core accessibility testing +- [ ] Lighthouse accessibility audit +- [ ] WAVE accessibility evaluation +- [ ] Color contrast analysis tools + +### User Testing +- [ ] Testing with users who rely on assistive technologies +- [ ] Usability testing with diverse user groups +- [ ] Feedback collection from accessibility community + +## Documentation Requirements + +For each component audit, document: +- [ ] Which WCAG criteria were tested +- [ ] Testing methods used +- [ ] Any accessibility issues found +- [ ] Severity level of issues (critical, major, minor) +- [ ] Recommended remediation steps +- [ ] Re-testing requirements + +## Compliance Levels + +### Priority Levels +- **Critical**: WCAG Level A violations that block access +- **High**: WCAG Level AA violations affecting usability +- **Medium**: WCAG best practices and Level AAA considerations +- **Low**: Enhancement opportunities for better accessibility + +### Sign-off Requirements +- [ ] Component passes all Level A criteria +- [ ] Component passes all Level AA criteria +- [ ] Manual testing completed +- [ ] Automated testing passes +- [ ] Documentation updated with accessibility notes + +## Resources + +- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/) +- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) +- [WebAIM Resources](https://webaim.org/) +- [A11y Project Checklist](https://www.a11yproject.com/checklist/) +- [Inclusive Components](https://inclusive-components.design/) \ No newline at end of file diff --git a/docs/design-system/audit-criteria.md b/docs/design-system/audit-criteria.md new file mode 100644 index 0000000..603a477 --- /dev/null +++ b/docs/design-system/audit-criteria.md @@ -0,0 +1,166 @@ +# Design System Audit Criteria + +## Overview + +This document establishes comprehensive audit criteria for evaluating design system compliance across all components in the Frontend Recipeer application. The audit framework ensures consistency, accessibility, and maintainability of our atomic design-based component system. + +## Audit Scope + +### Component Categories +Based on our atomic design methodology (as defined in [ADR-0001](../adr/0001-atomic-design-component-architecture.md)): + +- **Atoms**: Basic building blocks (Button, Input, Typography, etc.) +- **Molecules**: Simple combinations of atoms (QuantityAdjuster, DifficultyIndicator, etc.) +- **Organisms**: Complex sections with business logic (RecipeCard, NavigationMenu, etc.) +- **Templates**: Page layout structures +- **Foundation**: Design tokens (Colors, Typography, Spacing) + +### Evaluation Areas + +1. **Design Token Compliance** (25 points) +2. **Visual Consistency** (25 points) +3. **Accessibility Compliance** (25 points) +4. **Theme Support** (15 points) +5. **Documentation Quality** (10 points) + +**Total Score: 100 points** + +## 1. Design Token Compliance (25 points) + +### Colors (8 points) +- **CSS Variables Usage** (4 points) + - Uses semantic color tokens from `--primary`, `--secondary`, etc. (2 pts) + - No hardcoded color values in components (2 pts) +- **Theme Integration** (4 points) + - Properly responds to light/dark theme changes (2 pts) + - Uses `oklch()` color space as defined in tailwind.config.ts (2 pts) + +### Typography (8 points) +- **Font Family Consistency** (4 points) + - Uses defined font families (Playfair, Source Sans, etc.) (2 pts) + - Appropriate font choice for content type (2 pts) +- **Scale Adherence** (4 points) + - Uses standardized text sizes (text-xs to text-6xl) (2 pts) + - Consistent line-height and letter-spacing (2 pts) + +### Spacing (9 points) +- **Margin/Padding Standards** (5 points) + - Uses Tailwind spacing scale (0.5, 1, 1.5, 2, etc.) (3 pts) + - No arbitrary spacing values (2 pts) +- **Layout Consistency** (4 points) + - Consistent component spacing patterns (2 pts) + - Proper use of gap, padding, and margin (2 pts) + +## 2. Visual Consistency (25 points) + +### Component Variants (10 points) +- **Size Variants** (5 points) + - Consistent sizing system across similar components (3 pts) + - Proper variant implementation (sm, md, lg, xl) (2 pts) +- **State Variants** (5 points) + - Consistent hover, focus, active, disabled states (3 pts) + - Proper visual feedback for interactions (2 pts) + +### Layout Patterns (8 points) +- **Grid/Flexbox Usage** (4 points) + - Appropriate layout method selection (2 pts) + - Consistent alignment and distribution (2 pts) +- **Responsive Design** (4 points) + - Mobile-first approach implementation (2 pts) + - Consistent breakpoint usage (2 pts) + +### Visual Hierarchy (7 points) +- **Content Structure** (4 points) + - Clear information hierarchy (2 pts) + - Consistent heading levels and emphasis (2 pts) +- **Interactive Elements** (3 points) + - Clear call-to-action styling (2 pts) + - Consistent button/link treatments (1 pt) + +## 3. Accessibility Compliance (25 points) + +### WCAG 2.1 AA Requirements (15 points) +- **Color Contrast** (5 points) + - Text contrast ratio ≥ 4.5:1 for normal text (3 pts) + - Text contrast ratio ≥ 3:1 for large text (2 pts) +- **Keyboard Navigation** (5 points) + - All interactive elements keyboard accessible (3 pts) + - Logical tab order maintained (2 pts) +- **Screen Reader Support** (5 points) + - Proper semantic HTML usage (2 pts) + - ARIA labels and descriptions where needed (3 pts) + +### Interactive Accessibility (10 points) +- **Focus Management** (5 points) + - Visible focus indicators (2 pts) + - Focus trap implementation in modals (3 pts) +- **Form Accessibility** (5 points) + - Proper label associations (2 pts) + - Error message accessibility (2 pts) + - Required field indication (1 pt) + +## 4. Theme Support (15 points) + +### Light/Dark Mode (10 points) +- **Color Adaptation** (5 points) + - All colors adapt properly to theme changes (3 pts) + - No theme-specific hardcoded values (2 pts) +- **Visual Consistency** (5 points) + - Maintains visual hierarchy across themes (3 pts) + - Consistent component appearance (2 pts) + +### System Theme Detection (5 points) +- **Automatic Theme Detection** (3 points) + - Respects user's system preference (2 pts) + - Smooth theme transitions (1 pt) +- **Theme Persistence** (2 points) + - Remembers user's theme choice (2 pts) + +## 5. Documentation Quality (10 points) + +### Storybook Documentation (6 points) +- **Story Completeness** (4 points) + - All variants documented in stories (2 pts) + - Realistic usage examples provided (2 pts) +- **Story Organization** (2 points) + - Proper atomic hierarchy categorization (1 pt) + - Clear story titles and descriptions (1 pt) + +### Code Documentation (4 points) +- **TypeScript Interfaces** (2 points) + - Comprehensive prop interfaces with JSDoc (1 pt) + - Clear prop descriptions and examples (1 pt) +- **Usage Examples** (2 points) + - Component usage documented in stories (1 pt) + - Best practices and patterns documented (1 pt) + +## Scoring Guidelines + +### Score Ranges +- **90-100**: Excellent - Design system exemplar +- **80-89**: Good - Meets all standards with minor improvements needed +- **70-79**: Acceptable - Meets basic standards, some improvements needed +- **60-69**: Needs Improvement - Several issues to address +- **Below 60**: Requires Major Work - Significant design system violations + +### Priority Levels +- **Critical (90+ required)**: Atoms and foundational components +- **High (80+ required)**: Molecules and key organisms +- **Medium (70+ required)**: Complex organisms and templates +- **Low (60+ required)**: Experimental or legacy components + +## Audit Process + +1. **Component Selection**: Identify components for audit +2. **Evaluation**: Score each component using this criteria +3. **Documentation**: Record findings in audit tracking system +4. **Remediation**: Create action items for improvements +5. **Re-evaluation**: Re-audit after improvements implemented + +## Related Documents + +- [Scoring Methodology Guide](./scoring-methodology.md) +- [Accessibility Checklist](./accessibility-checklist.md) +- [Component Tracking Template](./component-audit-template.csv) +- [Audit Report Template](./audit-report-template.md) +- [ADR-0001: Atomic Design Component Architecture](../adr/0001-atomic-design-component-architecture.md) \ No newline at end of file diff --git a/docs/design-system/audit-report-template.md b/docs/design-system/audit-report-template.md new file mode 100644 index 0000000..c659ae2 --- /dev/null +++ b/docs/design-system/audit-report-template.md @@ -0,0 +1,293 @@ +# Design System Audit Report Template + +## Audit Information + +**Component**: [Component Name] +**Atomic Level**: [Atom/Molecule/Organism/Template] +**Auditor**: [Auditor Name] +**Audit Date**: [YYYY-MM-DD] +**Priority Level**: [Critical/High/Medium/Low] + +## Overall Score + +**Total Score**: [X/100] +**Status**: [Excellent/Good/Acceptable/Needs Improvement/Requires Major Work] + +### Score Breakdown +- **Design Token Compliance**: [X/25] +- **Visual Consistency**: [X/25] +- **Accessibility Compliance**: [X/25] +- **Theme Support**: [X/15] +- **Documentation Quality**: [X/10] + +## Detailed Evaluation + +### 1. Design Token Compliance (X/25) + +#### Colors (X/8) +**CSS Variables Usage** (X/4): +- ✅/❌ Uses semantic color tokens from design system +- ✅/❌ No hardcoded color values + +**Issues Found**: +- [List specific color-related issues] + +**Theme Integration** (X/4): +- ✅/❌ Properly responds to light/dark theme changes +- ✅/❌ Uses oklch() color space + +**Issues Found**: +- [List specific theme integration issues] + +#### Typography (X/8) +**Font Family Consistency** (X/4): +- ✅/❌ Uses defined font families appropriately +- ✅/❌ Appropriate font choice for content type + +**Scale Adherence** (X/4): +- ✅/❌ Uses standardized text sizes +- ✅/❌ Consistent line-height and letter-spacing + +**Issues Found**: +- [List specific typography issues] + +#### Spacing (X/9) +**Margin/Padding Standards** (X/5): +- ✅/❌ Uses Tailwind spacing scale exclusively +- ✅/❌ No arbitrary spacing values + +**Layout Consistency** (X/4): +- ✅/❌ Consistent component spacing patterns +- ✅/❌ Proper use of gap, padding, and margin + +**Issues Found**: +- [List specific spacing issues] + +### 2. Visual Consistency (X/25) + +#### Component Variants (X/10) +**Size Variants** (X/5): +- ✅/❌ Consistent sizing system +- ✅/❌ Proper variant implementation + +**State Variants** (X/5): +- ✅/❌ Consistent hover, focus, active, disabled states +- ✅/❌ Proper visual feedback for interactions + +**Issues Found**: +- [List specific variant issues] + +#### Layout Patterns (X/8) +**Grid/Flexbox Usage** (X/4): +- ✅/❌ Appropriate layout method selection +- ✅/❌ Consistent alignment and distribution + +**Responsive Design** (X/4): +- ✅/❌ Mobile-first approach implementation +- ✅/❌ Consistent breakpoint usage + +**Issues Found**: +- [List specific layout issues] + +#### Visual Hierarchy (X/7) +**Content Structure** (X/4): +- ✅/❌ Clear information hierarchy +- ✅/❌ Consistent heading levels and emphasis + +**Interactive Elements** (X/3): +- ✅/❌ Clear call-to-action styling +- ✅/❌ Consistent button/link treatments + +**Issues Found**: +- [List specific hierarchy issues] + +### 3. Accessibility Compliance (X/25) + +#### WCAG 2.1 AA Requirements (X/15) +**Color Contrast** (X/5): +- ✅/❌ Normal text ≥ 4.5:1 contrast ratio +- ✅/❌ Large text ≥ 3:1 contrast ratio + +**Testing Results**: +- Light theme: [contrast ratios] +- Dark theme: [contrast ratios] + +**Keyboard Navigation** (X/5): +- ✅/❌ All interactive elements keyboard accessible +- ✅/❌ Logical tab order maintained + +**Testing Results**: +- [Describe keyboard testing results] + +**Screen Reader Support** (X/5): +- ✅/❌ Proper semantic HTML usage +- ✅/❌ ARIA labels and descriptions where needed + +**Testing Results**: +- [Describe screen reader testing results] + +#### Interactive Accessibility (X/10) +**Focus Management** (X/5): +- ✅/❌ Visible focus indicators +- ✅/❌ Focus trap implementation (if applicable) + +**Form Accessibility** (X/5): +- ✅/❌ Proper label associations +- ✅/❌ Error message accessibility +- ✅/❌ Required field indication + +**Issues Found**: +- [List specific accessibility issues] + +### 4. Theme Support (X/15) + +#### Light/Dark Mode (X/10) +**Color Adaptation** (X/5): +- ✅/❌ All colors adapt properly to theme changes +- ✅/❌ No theme-specific hardcoded values + +**Visual Consistency** (X/5): +- ✅/❌ Maintains visual hierarchy across themes +- ✅/❌ Consistent component appearance + +**Testing Results**: +- [Describe theme switching testing] + +#### System Theme Detection (X/5) +**Automatic Theme Detection** (X/3): +- ✅/❌ Respects user's system preference +- ✅/❌ Smooth theme transitions + +**Theme Persistence** (X/2): +- ✅/❌ Remembers user's theme choice + +**Issues Found**: +- [List specific theme support issues] + +### 5. Documentation Quality (X/10) + +#### Storybook Documentation (X/6) +**Story Completeness** (X/4): +- ✅/❌ All variants documented in stories +- ✅/❌ Realistic usage examples provided + +**Story Organization** (X/2): +- ✅/❌ Proper atomic hierarchy categorization +- ✅/❌ Clear story titles and descriptions + +**Review Notes**: +- [Comments on story quality and completeness] + +#### Code Documentation (X/4) +**TypeScript Interfaces** (X/2): +- ✅/❌ Comprehensive prop interfaces with JSDoc +- ✅/❌ Clear prop descriptions and examples + +**Usage Examples** (X/2): +- ✅/❌ Component usage documented in stories +- ✅/❌ Best practices and patterns documented + +**Issues Found**: +- [List documentation issues] + +## Issues Summary + +### Critical Issues (Must Fix) +1. [Issue description with specific examples] +2. [Issue description with specific examples] + +### Major Issues (Should Fix) +1. [Issue description with specific examples] +2. [Issue description with specific examples] + +### Minor Issues (Nice to Fix) +1. [Issue description with specific examples] +2. [Issue description with specific examples] + +## Recommendations + +### Immediate Actions (Priority 1) +- [ ] [Specific action item with code examples if applicable] +- [ ] [Specific action item with code examples if applicable] + +### Short-term Improvements (Priority 2) +- [ ] [Specific action item] +- [ ] [Specific action item] + +### Long-term Enhancements (Priority 3) +- [ ] [Specific action item] +- [ ] [Specific action item] + +## Code Examples + +### Issues Found +```tsx +// ❌ Example of problematic code +className="bg-orange-500 text-white p-[15px]" +``` + +### Recommended Fixes +```tsx +// ✅ Corrected implementation +className="bg-primary text-primary-foreground p-4" +``` + +## Testing Evidence + +### Screenshots +- [Include screenshots showing issues] +- [Include before/after comparisons] + +### Test Results +- **Automated Testing**: [axe-core, Lighthouse results] +- **Manual Testing**: [Keyboard navigation, screen reader testing] +- **Cross-browser Testing**: [Results across different browsers] + +## Follow-up Actions + +### Re-audit Requirements +- [ ] Re-audit after critical issues are fixed +- [ ] Verify accessibility improvements with assistive technology users +- [ ] Test theme support across all variants +- [ ] Validate design token compliance + +### Next Audit Date +**Scheduled**: [YYYY-MM-DD] +**Reason**: [Trigger for next audit] + +## Approval + +### Review Status +- [ ] Technical review completed +- [ ] Accessibility review completed +- [ ] Design review completed +- [ ] Product owner approval + +### Sign-off +**Reviewed by**: [Name] +**Date**: [YYYY-MM-DD] +**Approved for**: [Production/Further Development/Requires Rework] + +## Appendix + +### Testing Tools Used +- [ ] Storybook visual testing +- [ ] Chrome DevTools accessibility panel +- [ ] axe DevTools browser extension +- [ ] WAVE accessibility evaluation +- [ ] Lighthouse audit +- [ ] Screen reader testing (specify which) +- [ ] Keyboard navigation testing +- [ ] Color contrast analyzers + +### Reference Materials +- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) +- [Frontend Recipeer Design System Audit Criteria](./audit-criteria.md) +- [Frontend Recipeer Scoring Methodology](./scoring-methodology.md) +- [Frontend Recipeer ADR-0001](../adr/0001-atomic-design-component-architecture.md) + +--- + +**Template Version**: 1.0 +**Last Updated**: [YYYY-MM-DD] +**Template Author**: [Name] \ No newline at end of file diff --git a/docs/design-system/component-audit-template.csv b/docs/design-system/component-audit-template.csv new file mode 100644 index 0000000..d0cf146 --- /dev/null +++ b/docs/design-system/component-audit-template.csv @@ -0,0 +1,42 @@ +Component Name,Atomic Level,Priority,Auditor,Audit Date,Design Token Compliance (25),Visual Consistency (25),Accessibility Compliance (25),Theme Support (15),Documentation Quality (10),Total Score (100),Status,Critical Issues,Major Issues,Minor Issues,Recommendations,Next Audit Date,Last Updated +Button,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Input,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Typography,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Label,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Checkbox,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Switch,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Textarea,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Avatar,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Badge,Atom,Critical,,,0,0,0,0,0,0,Not Audited,,,,"Initial audit required - critical atom component",,, +Progress,Atom,High,,,0,0,0,0,0,0,Not Audited,,,,"Audit after critical atoms completed",,, +Rating,Atom,High,,,0,0,0,0,0,0,Not Audited,,,,"Audit after critical atoms completed",,, +Separator,Atom,High,,,0,0,0,0,0,0,Not Audited,,,,"Audit after critical atoms completed",,, +Skeleton,Atom,High,,,0,0,0,0,0,0,Not Audited,,,,"Audit after critical atoms completed",,, +AspectRatio,Atom,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Audit after high priority components",,, +QuantityAdjuster,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Key interaction molecule - high priority",,, +DifficultyIndicator,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Core recipe component - high priority",,, +ThemeToggle,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Critical theme functionality",,, +RadioGroup,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Important form component",,, +Select,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Important form component",,, +Slider,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Important form component",,, +Card,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Foundational layout component",,, +Alert,Molecule,High,,,0,0,0,0,0,0,Not Audited,,,,"Critical feedback component",,, +Accordion,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Content organization component",,, +AlertDialog,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Important interaction component",,, +Breadcrumb,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Navigation helper component",,, +Drawer,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Mobile navigation component",,, +HoverCard,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Content preview component",,, +Popover,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Contextual content component",,, +Sheet,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Mobile interaction component",,, +Table,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Data display component",,, +Tabs,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Content organization component",,, +Timer,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Recipe-specific component",,, +Toast,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Notification component",,, +Tooltip,Molecule,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Information component",,, +RecipeCard,Organism,High,,,0,0,0,0,0,0,Not Audited,,,,"Core application component - business critical",,, +IngredientChecklist,Organism,High,,,0,0,0,0,0,0,Not Audited,,,,"Core recipe functionality",,, +NutritionFacts,Organism,High,,,0,0,0,0,0,0,Not Audited,,,,"Important recipe information",,, +NavigationMenu,Organism,High,,,0,0,0,0,0,0,Not Audited,,,,"Core app navigation",,, +RecipeCollectionSaver,Organism,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Recipe management feature",,, +LoginForm,Organism,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Authentication component",,, +Dialog,Organism,Medium,,,0,0,0,0,0,0,Not Audited,,,,"Modal interaction component",,, \ No newline at end of file diff --git a/docs/design-system/example-button-audit.md b/docs/design-system/example-button-audit.md new file mode 100644 index 0000000..3bfbbfa --- /dev/null +++ b/docs/design-system/example-button-audit.md @@ -0,0 +1,272 @@ +# Example Audit Report: Button Component + +## Audit Information + +**Component**: Button +**Atomic Level**: Atom +**Auditor**: Design System Team +**Audit Date**: 2024-12-29 +**Priority Level**: Critical + +## Overall Score + +**Total Score**: 92/100 +**Status**: Excellent - Design system exemplar + +### Score Breakdown +- **Design Token Compliance**: 23/25 +- **Visual Consistency**: 24/25 +- **Accessibility Compliance**: 23/25 +- **Theme Support**: 15/15 +- **Documentation Quality**: 7/10 + +## Detailed Evaluation + +### 1. Design Token Compliance (23/25) + +#### Colors (8/8) +**CSS Variables Usage** (4/4): +- ✅ Uses semantic color tokens from design system (`bg-primary`, `text-primary-foreground`) +- ✅ No hardcoded color values found + +**Theme Integration** (4/4): +- ✅ Properly responds to light/dark theme changes +- ✅ Uses oklch() color space as defined in tailwind.config.ts + +**Issues Found**: None + +#### Typography (7/8) +**Font Family Consistency** (4/4): +- ✅ Uses appropriate font families from design system +- ✅ Font choice matches button interaction patterns + +**Scale Adherence** (3/4): +- ✅ Uses standardized text sizes (text-sm, text-base, text-lg) +- ⚠️ Minor inconsistency in line-height for XL variant + +**Issues Found**: +- XL button variant could use more consistent line-height scaling + +#### Spacing (8/9) +**Margin/Padding Standards** (5/5): +- ✅ Uses Tailwind spacing scale exclusively (px-3, px-4, px-6) +- ✅ No arbitrary spacing values found + +**Layout Consistency** (3/4): +- ✅ Consistent component spacing patterns +- ⚠️ Icon spacing could be more systematic across sizes + +**Issues Found**: +- Icon spacing in different button sizes needs standardization + +### 2. Visual Consistency (24/25) + +#### Component Variants (10/10) +**Size Variants** (5/5): +- ✅ Excellent size progression (sm, md, lg, xl) +- ✅ Consistent sizing system with proper scaling + +**State Variants** (5/5): +- ✅ Comprehensive hover, focus, active, disabled states +- ✅ Excellent visual feedback for all interactions + +**Issues Found**: None + +#### Layout Patterns (8/8) +**Grid/Flexbox Usage** (4/4): +- ✅ Appropriate flexbox usage for button content +- ✅ Perfect alignment and distribution + +**Responsive Design** (4/4): +- ✅ Mobile-first approach correctly implemented +- ✅ Consistent breakpoint usage + +**Issues Found**: None + +#### Visual Hierarchy (6/7) +**Content Structure** (4/4): +- ✅ Clear visual hierarchy with variants +- ✅ Consistent emphasis patterns + +**Interactive Elements** (2/3): +- ✅ Excellent call-to-action styling +- ⚠️ Minor inconsistency in secondary button treatment + +**Issues Found**: +- Secondary button could have slightly more distinction from default + +### 3. Accessibility Compliance (23/25) + +#### WCAG 2.1 AA Requirements (14/15) +**Color Contrast** (5/5): +- ✅ Primary buttons: 5.2:1 contrast ratio (exceeds 4.5:1) +- ✅ Secondary buttons: 4.7:1 contrast ratio (exceeds 4.5:1) + +**Testing Results**: +- Light theme: All variants pass WCAG AA +- Dark theme: All variants pass WCAG AA + +**Keyboard Navigation** (5/5): +- ✅ All button variants keyboard accessible +- ✅ Logical tab order maintained + +**Testing Results**: +- Tab navigation works perfectly +- Enter and Space activation confirmed + +**Screen Reader Support** (4/5): +- ✅ Proper semantic HTML (button element) +- ⚠️ Loading state could announce better to screen readers + +**Testing Results**: +- Basic button functionality announced correctly +- Loading state needs aria-live region + +#### Interactive Accessibility (9/10) +**Focus Management** (5/5): +- ✅ Excellent visible focus indicators +- ✅ Focus trap not applicable (atomic component) + +**Form Accessibility** (4/5): +- ✅ Works well as form submission button +- ⚠️ Could better support form validation states + +**Issues Found**: +- Loading state announcements need improvement +- Form integration could be enhanced + +### 4. Theme Support (15/15) + +#### Light/Dark Mode (10/10) +**Color Adaptation** (5/5): +- ✅ All colors adapt perfectly to theme changes +- ✅ No theme-specific hardcoded values + +**Visual Consistency** (5/5): +- ✅ Maintains perfect visual hierarchy across themes +- ✅ Consistent component appearance + +**Testing Results**: +- Theme switching tested extensively - perfect adaptation + +#### System Theme Detection (5/5) +**Automatic Theme Detection** (3/3): +- ✅ Respects user's system preference +- ✅ Smooth theme transitions + +**Theme Persistence** (2/2): +- ✅ Remembers user's theme choice + +**Issues Found**: None + +### 5. Documentation Quality (7/10) + +#### Storybook Documentation (4/6) +**Story Completeness** (2/4): +- ✅ All variants documented in stories +- ⚠️ Could use more realistic usage examples in complex scenarios + +**Story Organization** (2/2): +- ✅ Proper atomic hierarchy categorization ("Atoms/Button") +- ✅ Clear story titles and descriptions + +**Review Notes**: +- Basic stories are excellent but could show more real-world usage patterns + +#### Code Documentation (3/4) +**TypeScript Interfaces** (2/2): +- ✅ Comprehensive ButtonProps interface with JSDoc +- ✅ Clear prop descriptions and examples + +**Usage Examples** (1/2): +- ✅ Component usage well documented in stories +- ⚠️ Could document more best practices and common patterns + +**Issues Found**: +- Missing advanced usage patterns in documentation +- Could show more composition examples + +## Issues Summary + +### Critical Issues (Must Fix) +None identified - component meets critical atom standards. + +### Major Issues (Should Fix) +None identified - excellent implementation overall. + +### Minor Issues (Nice to Fix) +1. **Line-height consistency**: XL button variant line-height scaling +2. **Icon spacing**: Systematic icon spacing across all button sizes +3. **Screen reader announcements**: Loading state aria-live announcements +4. **Documentation enhancement**: More real-world usage examples + +## Recommendations + +### Immediate Actions (Priority 1) +- [ ] Add aria-live region for loading state announcements +- [ ] Standardize icon spacing across all button size variants + +### Short-term Improvements (Priority 2) +- [ ] Improve line-height scaling for XL variant +- [ ] Enhance secondary button visual distinction +- [ ] Add more realistic usage examples to Storybook + +### Long-term Enhancements (Priority 3) +- [ ] Document advanced composition patterns +- [ ] Create button group component for related actions +- [ ] Consider form validation state integration + +## Code Examples + +### Recommended Improvements + +#### Loading State Accessibility +```tsx +// ✅ Improved loading state + +``` + +#### Icon Spacing Standardization +```tsx +// ✅ Consistent icon spacing +const iconSpacing = { + sm: "gap-1.5", + md: "gap-2", + lg: "gap-2.5", + xl: "gap-3" +} +``` + +## Follow-up Actions + +### Re-audit Requirements +- [ ] Re-audit after accessibility improvements +- [ ] Verify icon spacing improvements +- [ ] Test enhanced loading state with screen readers + +### Next Audit Date +**Scheduled**: 2025-03-29 +**Reason**: Quarterly review of critical atom components + +## Approval + +### Review Status +- [x] Technical review completed +- [x] Accessibility review completed +- [x] Design review completed +- [x] Product owner approval + +### Sign-off +**Reviewed by**: Design System Team +**Date**: 2024-12-29 +**Approved for**: Production - Excellent example of design system standards + +--- + +**Report demonstrates**: How comprehensive audit methodology works for critical components +**Score justification**: 92/100 reflects excellent implementation with minor enhancement opportunities +**Next steps**: Use as baseline standard for other atomic components \ No newline at end of file diff --git a/docs/design-system/scoring-methodology.md b/docs/design-system/scoring-methodology.md new file mode 100644 index 0000000..b4b94bb --- /dev/null +++ b/docs/design-system/scoring-methodology.md @@ -0,0 +1,318 @@ +# Design System Scoring Methodology + +## Overview + +This guide provides detailed instructions for scoring components against our design system audit criteria. Each evaluation area has specific measurement techniques and examples to ensure consistent scoring across all auditors. + +## Scoring Scale + +### Point Values +- **Full Points**: Meets criteria completely with no issues +- **Partial Points**: Meets criteria with minor deviations or improvements needed +- **Half Points**: Partially meets criteria with moderate issues +- **No Points**: Does not meet criteria or has significant violations + +### Evaluation Evidence +Each score must be supported by: +- **Code Review**: Direct examination of component source +- **Visual Testing**: Storybook story verification +- **Accessibility Testing**: Screen reader and keyboard testing +- **Theme Testing**: Light/dark mode validation + +## 1. Design Token Compliance (25 points) + +### Colors (8 points) + +#### CSS Variables Usage (4 points) +**Full Points (4)**: Component exclusively uses semantic color tokens +```tsx +// ✅ Correct usage +className="bg-primary text-primary-foreground" +className="border-border hover:bg-accent" +``` + +**Partial Points (2-3)**: Mostly uses tokens with 1-2 minor hardcoded values +```tsx +// ⚠️ Mostly correct but has some hardcoded values +className="bg-primary text-white" // should use primary-foreground +``` + +**No Points (0)**: Uses hardcoded colors or non-semantic values +```tsx +// ❌ Incorrect usage +className="bg-orange-500 text-gray-900" +style={{ backgroundColor: '#ff6b35' }} +``` + +**Measurement Process**: +1. Search component code for color classes and inline styles +2. Verify all colors use design token variables +3. Check for any hex codes, rgb values, or arbitrary color classes +4. Review hover, focus, and active states + +#### Theme Integration (4 points) +**Full Points (4)**: Perfect theme adaptation with oklch() usage +**Partial Points (2-3)**: Good theme support with minor issues +**No Points (0)**: Poor or missing theme support + +**Testing Process**: +1. Toggle between light and dark themes in Storybook +2. Verify all colors adapt appropriately +3. Check for visual consistency across themes +4. Validate oklch() color space usage in generated CSS + +### Typography (8 points) + +#### Font Family Consistency (4 points) +**Full Points (4)**: Uses appropriate font families from design system +```tsx +// ✅ Correct usage +className="font-playfair text-2xl" // Headlines +className="font-source-sans text-base" // Body text +className="font-caveat text-lg" // Handwritten accents +``` + +**Measurement Process**: +1. Review component for font-family usage +2. Verify fonts match content purpose (headings, body, accents) +3. Check consistency with design system font choices +4. Validate no arbitrary font declarations + +#### Scale Adherence (4 points) +**Testing Process**: +1. Verify text sizes use Tailwind scale (text-xs through text-6xl) +2. Check line-height consistency (leading classes) +3. Review letter-spacing usage (tracking classes) +4. Ensure no arbitrary text sizing + +### Spacing (9 points) + +#### Margin/Padding Standards (5 points) +**Full Points (5)**: Exclusive use of Tailwind spacing scale +```tsx +// ✅ Correct usage +className="p-4 m-2 gap-3 space-y-6" +``` + +**Partial Points (2-4)**: Mostly correct with minor arbitrary values +```tsx +// ⚠️ Mostly correct but has arbitrary value +className="p-4 m-[15px]" // should use standard scale +``` + +**No Points (0)**: Frequent arbitrary spacing or inconsistent patterns +```tsx +// ❌ Incorrect usage +style={{ padding: '13px', margin: '7px 15px' }} +``` + +**Measurement Process**: +1. Search for all padding, margin, and gap classes +2. Verify adherence to Tailwind spacing scale (0.5, 1, 1.5, 2, 2.5, 3, etc.) +3. Check for arbitrary values in square brackets +4. Review spacing consistency patterns + +## 2. Visual Consistency (25 points) + +### Component Variants (10 points) + +#### Size Variants (5 points) +**Full Points (5)**: Comprehensive, consistent size system +```tsx +// ✅ Excellent size variant system +const sizeVariants = { + sm: "h-8 px-3 text-sm", + md: "h-10 px-4 text-base", + lg: "h-12 px-6 text-lg", + xl: "h-14 px-8 text-xl" +} +``` + +**Measurement Process**: +1. Review component variants in Storybook +2. Check size progression logic and consistency +3. Compare similar components for size alignment +4. Verify all documented variants render correctly + +#### State Variants (5 points) +**Testing Process**: +1. Test hover states in Storybook +2. Verify focus indicators with keyboard navigation +3. Check disabled state visual feedback +4. Test active/pressed states +5. Validate loading states if applicable + +### Layout Patterns (8 points) + +#### Grid/Flexbox Usage (4 points) +**Full Points (4)**: Optimal layout method with proper implementation +**Measurement Process**: +1. Review layout methodology choice (grid vs flex) +2. Check alignment and distribution properties +3. Verify responsive behavior +4. Validate semantic appropriateness of layout choice + +### Visual Hierarchy (7 points) + +#### Content Structure (4 points) +**Testing Process**: +1. Review heading structure (h1-h6) semantic correctness +2. Check visual weight progression +3. Verify emphasis patterns (bold, italic, color) +4. Validate information hierarchy clarity + +## 3. Accessibility Compliance (25 points) + +### WCAG 2.1 AA Requirements (15 points) + +#### Color Contrast (5 points) +**Measurement Tools**: +- Browser DevTools Accessibility Panel +- WebAIM Contrast Checker +- Lighthouse Accessibility Audit + +**Testing Process**: +1. Measure text contrast ratios in both light and dark themes +2. Check normal text (4.5:1 minimum) vs large text (3:1 minimum) +3. Test interactive element contrast ratios +4. Verify focus indicator contrast + +**Full Points (5)**: All text meets or exceeds contrast requirements +**Partial Points (2-4)**: Most text meets requirements with minor issues +**No Points (0)**: Multiple contrast failures + +#### Keyboard Navigation (5 points) +**Testing Process**: +1. Tab through all interactive elements +2. Verify logical tab order +3. Test Enter/Space key activation +4. Check Escape key functionality in modals +5. Validate arrow key navigation where appropriate + +#### Screen Reader Support (5 points) +**Testing Tools**: +- NVDA (Windows) +- VoiceOver (macOS) +- Chrome's Screen Reader extension + +**Testing Process**: +1. Navigate component with screen reader +2. Verify semantic HTML structure +3. Check ARIA labels and descriptions +4. Test dynamic content announcements +5. Validate form label associations + +### Interactive Accessibility (10 points) + +#### Focus Management (5 points) +**Testing Process**: +1. Verify visible focus indicators on all interactive elements +2. Test focus trap in modals and dialogs +3. Check focus restoration after modal close +4. Validate focus bypass options for complex components + +#### Form Accessibility (5 points) +**Testing Process**: +1. Check label-input associations (for/id attributes) +2. Test error message announcements +3. Verify required field indication (visual and programmatic) +4. Test field validation feedback +5. Check fieldset/legend usage for grouped inputs + +## 4. Theme Support (15 points) + +### Light/Dark Mode (10 points) + +#### Color Adaptation (5 points) +**Testing Process**: +1. Switch themes in Storybook or application +2. Verify all colors adapt appropriately +3. Check for any hardcoded theme-specific values +4. Test color accessibility in both themes + +**Scoring Examples**: +- **Full Points (5)**: Perfect adaptation, maintains design intent +- **Partial Points (3-4)**: Good adaptation with minor issues +- **Half Points (2)**: Partial adaptation with some elements not changing +- **No Points (0)**: Poor or no theme adaptation + +### System Theme Detection (5 points) +**Testing Process**: +1. Test system theme preference detection +2. Verify smooth theme transitions +3. Check theme persistence across sessions +4. Test programmatic theme switching + +## 5. Documentation Quality (10 points) + +### Storybook Documentation (6 points) + +#### Story Completeness (4 points) +**Review Checklist**: +- [ ] Default/basic story exists +- [ ] All variants documented with stories +- [ ] Interactive examples provided +- [ ] Realistic mock data used +- [ ] Edge cases demonstrated + +**Scoring**: +- **Full Points (4)**: All checklist items completed +- **Partial Points (2-3)**: Most items completed +- **No Points (0)**: Missing stories or poor examples + +### Code Documentation (4 points) + +#### TypeScript Interfaces (2 points) +**Review Checklist**: +- [ ] Props interface exists with JSDoc comments +- [ ] All props documented with descriptions +- [ ] Types are specific and accurate +- [ ] Examples provided in comments + +#### Usage Examples (2 points) +**Review Checklist**: +- [ ] Basic usage example in stories +- [ ] Advanced usage patterns documented +- [ ] Best practices mentioned +- [ ] Common pitfalls addressed + +## Quality Assurance + +### Audit Consistency +- Multiple auditors should review high-priority components +- Scoring discrepancies should be discussed and resolved +- Regular calibration sessions to maintain scoring consistency +- Sample audits should be cross-validated + +### Documentation Requirements +Each audit must include: +- Component name and atomic level +- Auditor name and date +- Detailed scoring breakdown +- Specific improvement recommendations +- Screenshots or code examples for issues found +- Priority level for remediation + +### Re-audit Triggers +Components should be re-audited when: +- Major code changes occur +- Design system updates are implemented +- Accessibility requirements change +- New browser support is added +- Performance optimizations are made + +## Tools and Resources + +### Recommended Tools +- **Storybook**: Component documentation and testing +- **Chrome DevTools**: Accessibility and performance auditing +- **WAVE**: Web accessibility evaluation +- **axe DevTools**: Automated accessibility testing +- **Lighthouse**: Comprehensive auditing +- **Figma**: Design comparison and measurement + +### Reference Materials +- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) +- [Tailwind CSS Documentation](https://tailwindcss.com/docs) +- [Atomic Design Methodology](https://atomicdesign.bradfrost.com/) +- [Frontend Recipeer ADR-0001](../adr/0001-atomic-design-component-architecture.md) \ No newline at end of file