Design System Project — Build an Accessible Component Library

In this tutorial, you will learn about Design System Project. We cover key concepts, practical examples, and best practices to help you master this topic.

The design system project asks you to create 5 accessible components with design tokens, documentation, keyboard support, focus management, automated testing, and contribution guidelines for a design system.

What You'll Learn

You will apply everything from this module by building an accessible component library with design tokens, components, documentation, testing, and contribution guidelines.

Why It Matters

Theory without practice is forgettable. This project gives you hands-on experience building accessible components for a design system, preparing you to contribute to or build real-world design systems.

Real-World Use

DodaTech's new team members complete this project to learn DodaKit's Accessibility standards. The deliverable is reviewed against the same checklist used for production components.

flowchart LR
  A[Design Tokens] --> B[Color System]
  B --> C[Typography]
  C --> D[Components]
  D --> E[Documentation]
  E --> F[Testing]
  F --> G[Contribution Guide]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Project Requirements

1. Create an accessible design token set with color, typography, spacing, and focus tokens
2. Build 5 accessible components (button, text input, accordion, modal, navigation)
3. Write accessibility documentation for each component
4. Add automated accessibility tests
5. Create contribution guidelines with accessibility checklist
6. Submit a project report

Component Requirements

For each component:

• Use semantic HTML first, ARIA only when necessary
• Full keyboard operability with documented key bindings
• Visible focus indicator using design system tokens
• Color pairs meeting WCAG AA contrast
• Tested with automated tools and screen reader
• Accessibility documentation with ARIA, keyboard, focus, contrast, testing

// Project deliverable validator
class DesignSystemProject {
  constructor(projectName) {
    this.name = projectName;
    this.tokens = { color: [], typography: [], spacing: [], focus: [] };
    this.components = [];
    this.documentation = {};
    this.tests = [];
    this.guidelines = null;
  }

  addToken(category, name, value, accessible) {
    if (!this.tokens[category]) return { error: 'Unknown category' };
    this.tokens[category].push({ name, value, accessible });
    return { category, name, accessible };
  }

  addComponent(name, features) {
    const checks = {
      semanticHTML: features.includes('semantic'),
      keyboardOperable: features.includes('keyboard'),
      focusVisible: features.includes('focus'),
      contrastPass: features.includes('contrast'),
      screenReaderTested: features.includes('screen-reader'),
      documented: features.includes('documented'),
      tested: features.includes('tested')
    };

    this.components.push({
      name: name,
      checks: checks,
      complete: Object.values(checks).every(v => v === true)
    });

    return { name, complete: Object.values(checks).every(v => v === true) };
  }

  getProjectStatus() {
    const componentStatus = this.components.map(c => ({
      name: c.name,
      complete: c.complete,
      missing: Object.entries(c.checks)
        .filter(([k, v]) => !v)
        .map(([k]) => k)
    }));

    const allComplete = this.components.length >= 5 &&
      this.components.every(c => c.complete) &&
      Object.values(this.tokens).flat().length >= 10 &&
      this.guidelines !== null;

    return {
      project: this.name,
      tokens: Object.values(this.tokens).flat().length,
      components: this.components.length,
      componentsComplete: this.components.filter(c => c.complete).length,
      allComplete: allComplete,
      componentDetails: componentStatus,
      remainingTokens: Math.max(0, 10 - Object.values(this.tokens).flat().length),
      remainingComponents: Math.max(0, 5 - this.components.length)
    };
  }
}

const project = new DesignSystemProject('DodaKit Mini');
project.addToken('color', 'text-primary', '#1a1a1a', true);
project.addToken('color', 'background', '#ffffff', true);
project.addToken('typography', 'body-size', '1rem', true);
project.addToken('spacing', 'touch-target', '44px', true);

project.addComponent('Button', ['semantic', 'keyboard', 'focus', 'contrast', 'tested']);
project.addComponent('TextInput', ['semantic', 'keyboard', 'focus', 'contrast', 'screen-reader', 'tested']);
project.addComponent('Modal', ['semantic', 'keyboard', 'focus', 'contrast']);

console.log(project.getProjectStatus());

Expected output:

{
  project: 'DodaKit Mini',
  tokens: 4,
  components: 3,
  componentsComplete: 0,
  allComplete: false,
  componentDetails: [
    { name: 'Button', complete: false, missing: ['documented'] },
    { name: 'TextInput', complete: false, missing: ['documented'] },
    { name: 'Modal', complete: false, missing: ['screenReaderTested', 'documented', 'tested'] }
  ],
  remainingTokens: 6,
  remainingComponents: 2
}

Deliverable Template

Submit the following:

1. tokens.css — Design token definitions
2. components/ — 5 component implementations (HTML + CSS + JS)
3. docs/ — Accessibility documentation per component
4. tests/ — Automated accessibility test file
5. CONTRIBUTING.md — Contribution guidelines with accessibility checklist
6. README.md — Project overview

Evaluation Criteria

• All components use semantic HTML
• Keyboard operability is complete
• Focus indicators are visible and consistent
• Color pairs meet WCAG AA
• Documentation covers all required sections
• Contribution guidelines include enforceable checklist

Common Mistakes

1. Not Using Semantic HTML

Custom div-based components without ARIA fail accessibility. Use button, input, nav, and other native elements.

2. Skipping Documentation

Components without accessibility documentation cannot be used correctly by other developers.

3. Incomplete Keyboard Support

Missing arrow key navigation on tabs, missing Escape on modals, missing Enter on buttons.

4. Focus Management Missing

Modals without focus traps, returning focus to wrong element, no focus on dynamic content.

5. Not Testing with Screen Reader

Components that seem accessible visually may be unusable with screen readers.

6. Forgetting Contribution Guidelines

A design system without contribution guidelines cannot scale. Include the checklist.

7. Too Few Tokens

A design system needs at least 10 tokens across categories to be useful.

Practice Questions

1. How many components are required for this project?

5 components: button, text input, accordion, modal, and navigation.

2. What must each component include for accessibility?

Semantic HTML, keyboard support, focus indicator, WCAG AA contrast, and documentation.

3. How many design tokens are required?

At least 10 tokens across color, typography, spacing, and focus categories.

4. What should the contribution guidelines include?

An accessibility checklist with ARIA, keyboard, focus, contrast, testing, and documentation requirements.

5. Challenge: Complete the full project for a real design system. Have your components reviewed by an accessibility expert.

FAQ

Mini Project

This is the final project for this module. Complete all deliverables: tokens, 5 components, documentation, tests, and contribution guidelines.

What's Next

You have completed the Accessibility in Design Systems module. Continue to VPAT / ACR to learn about accessibility conformance reporting. Or revisit Cognitive Accessibility for deeper understanding of designing for neurodivergent users.