Building Atman Design System

Project Overview

Atman (from Sanskrit, meaning "essence" or "soul") is a lean, accessible, and modern Design System built with Web Components. It was created as a portfolio piece to demonstrate the end-to-end development of a design system by a single person with AI assistance.

The goal was to build a complete, production-ready design system as a single-person effort powered by AI. From design tokens to accessible components to documentation, every piece ships with WCAG AA compliance, TypeScript types, Storybook stories, and dark mode support.

The Author

I'm Rafael Craice, a Product Designer with deep frontend experience. Atman represents the intersection of my design practice and technical background, showcasing what's possible when a designer has the skills to build their own design system from scratch.

Design Decisions

Philosophy: Essentialism

Atman follows a lean philosophy. Where many design systems offer dozens of variants, multiple size options, and extensive configuration, Atman deliberately provides the minimum needed to build functional, beautiful applications:

• 3 sizes (sm, md, lg) instead of 5+
• 4 button variants (primary, secondary, ghost, destructive) — covering all real use cases
• 16 components for v1 — carefully selected to support actual application needs
• Limited color palette — primary, secondary, success, warning, destructive, and a neutral scale

Token System

The design token system is built on an 8px grid with a spacing scale of 4, 8, 12, 16, 24, 32, 48, 64, and 96 pixels. Typography uses Geist, Vercel's open-source font family, chosen for its excellent readability and modern aesthetic.

All tokens are implemented as CSS Custom Properties (--atman-*), enabling runtime theming and framework-agnostic consumption. The system includes 300+ tokens covering colors, spacing, typography, shadows, border radius, transitions, z-index, and focus styles.

Component API Standards

Every component follows strict conventions:

• Naming: All elements use the atman- prefix (<atman-button>, <atman-input>)
• Events: Custom events prefixed with atman- and dispatched with bubbles: true, composed: true
• Slots: Default slot for main content, named slots for specific areas
• CSS Parts: All components expose ::part() for external styling
• Types: Exported TypeScript types for all properties and events

Technical Architecture

Why Web Components?

Web Components were chosen specifically for framework-agnostic distribution. A design system that only works with React or Vue limits adoption. Web Components work everywhere — React, Vue, Angular, Svelte, or plain HTML. They use the platform, not a framework.

Lit was selected over raw custom elements for its ergonomic features: reactive properties, efficient DOM updates via lit-html, scoped styles, and TypeScript decorators. The trade-off is a small runtime dependency (~7KB gzipped), which is acceptable for the developer experience gained.

Shadow DOM: Encapsulation vs. Flexibility

All components use Shadow DOM for style encapsulation. This guarantees components look correct regardless of the host application's CSS. The downside is that external styling requires ::part() selectors or CSS Custom Properties, but this is by design — it prevents accidental style leakage and ensures visual consistency.

Accessibility Approach

Accessibility is not an afterthought in Atman — it's a baseline requirement. Every component was built with WCAG AA compliance from the start, and a full accessibility audit (Phase 7) validated and fixed remaining issues.

Key Accessibility Features

• Keyboard navigation: Full keyboard support for all interactive elements. Arrow keys in Select, Tabs, and Radio groups. Focus trap in Modal.
• Screen reader support: Proper ARIA attributes, roles, and live regions. Semantic HTML structure.
• Focus management: Visible focus indicators using a consistent focus ring system. Focus is trapped in modals and restored on close.
• Color contrast: All text and UI elements meet WCAG AA minimum contrast ratios (4.5:1 for text, 3:1 for UI elements).
• Reduced motion: All animations respect prefers-reduced-motion via a global media query.

AI-Assisted Development

Atman was built using an AI-assisted development approach where the human provides direction, vision, and quality control while an AI assistant (Claude Code by Anthropic) handles the implementation details.

How It Worked

The entire project was guided by a single document that served as the project brief, technical specification, and progress tracker. This document defined:

• Design philosophy and constraints
• Component specifications with sizes, variants, and features
• Technical standards (naming, events, accessibility)
• Development phases with clear deliverables

Each development session followed a pattern: start a phase, let Claude Code implement the components and documentation, review the output, iterate on details, and move to the next phase.

What Worked Well

• Speed: 16 components, full Storybook documentation, and accessibility audit completed in a focused development sprint
• Consistency: The AI maintained consistent patterns across all components because the conventions were defined upfront
• Documentation: Storybook stories were generated alongside components, ensuring documentation stayed in sync
• Accessibility: ARIA patterns and keyboard navigation were implemented correctly from the start, with the audit catching edge cases

What Required Human Judgment

• Design decisions: Color choices, spacing scale, component selection — these required design intuition
• Quality bar: Knowing when a component "feels right" in terms of interaction quality
• Architecture: High-level decisions about technology stack, project structure, and API conventions
• Prioritization: Deciding which 16 components to build for v1 out of dozens of possibilities

Results

Deliverables

• Component library with 16 production-ready Web Components
• Design token system with 300+ CSS Custom Properties, light and dark themes
• Storybook documentation with interactive examples, accessibility notes, and code snippets
• Figma Tokens Studio integration for design-to-code synchronization
• Full WCAG AA compliance verified through accessibility audit
• GitHub Pages deployment with CI/CD pipeline
• TypeScript support with exported types and IntelliSense

Development Phases

• Phase 1: Foundation Repository, tokens, base styles
• Phase 2: Primitives Button, Badge, Avatar, Icon
• Phase 3: Form Controls Input, Select, Checkbox, Radio
• Phase 4: Feedback Alert, Toast, Skeleton, Tooltip
• Phase 5: Layout Card, Modal, Tabs, Divider
• Phase 6: Documentation Storybook, GitHub Pages, README
• Phase 7: Accessibility Audit WCAG AA compliance verification
• Phase 8: Figma Tokens Tokens Studio integration
• Phase 9: Portfolio Landing page and case study

Learnings

On Design Systems

Start with constraints. Defining a limited set of sizes, variants, and components upfront made every subsequent decision easier. When in doubt, leave it out — you can always add later, but removing is painful.

Tokens are the foundation. Getting the design token system right early saved enormous effort later. Every component references tokens, so changes propagate consistently. The time invested in the token structure paid dividends throughout the project.

On AI-Assisted Development

The brief is everything. The quality of Claude Code's output was directly proportional to the clarity of the project brief. The atman.md document served as both specification and context, enabling the AI to maintain consistency across sessions.

Human taste is irreplaceable. AI is excellent at implementing patterns once defined, but the design decisions — what feels right, what to prioritize, how to balance trade-offs — still require human judgment and design experience.

Review is essential. AI-generated code needs the same code review rigor as human-written code. The accessibility audit (Phase 7) caught issues that were technically correct but suboptimal from a user experience perspective.

Future Plans

Phase 10 will add 8 additional components: Switch, Progress, Accordion, Breadcrumb, Textarea, Pagination, Dropdown Menu, and Table. The foundation is solid — adding components now follows well-established patterns.