Aruuri Design System & UI Components

The Aruuri platform is built on a robust and meticulously crafted design system, ensuring consistency, accessibility, and an exceptional user experience across all its interfaces. This system integrates design principles and technical implementation into a cohesive workflow, centralizing design decisions from visual elements to interactive components.

Core Design Principles

Our design system adheres to fundamental principles that guide every aspect of its development:

1. Single Source of Truth: Design decisions originate in Figma. Figma variables are transformed into design tokens, which then inform the styling of all UI components. This ensures that every visual element in the application directly reflects the approved design language, eliminating discrepancies and maintaining brand consistency. There are no raw hex codes or px values directly in components; all styling uses CSS variables derived from tokens.
2. 1:1 Naming Convention: To bridge the gap between design and development, a strict 1:1 naming convention is enforced. Figma component and variant names (e.g., Button variant=primary size=md) precisely match their corresponding code props (e.g., <Button variant="primary" size="md" />). This reduces cognitive load for developers and ensures a seamless translation from design mockups to functional code.
3. Accessibility First: Accessibility (a11y) is a non-negotiable requirement. All components are designed and developed with WCAG 2.2 AA compliance in mind, supporting keyboard navigation, screen reader technologies, and undergoing automated accessibility checks within Storybook.

Design Tokens Workflow

The heart of Aruuri's visual consistency lies in its design tokens. These are the atomic units of our design system, representing styling values like colors, typography, spacing, and more.

The workflow is as follows:

1. Figma Variables: Design values are defined as variables in Figma. This acts as the primary source for all design decisions.
2. tokens.json Export: These Figma variables are then exported into a tokens.json file.
3. Style Dictionary Transformation: The tokens.json file is processed by Style Dictionary↗, configured via packages/design-tokens/config.js. This configuration leverages @tokens-studio/sd-transforms to expand composite tokens (like typography and shadow) and apply consistent naming conventions (e.g., kebab-case for CSS variables, camel-case for JavaScript).
4. CSS Variable Output: Style Dictionary generates a tokens.css file (packages/design-tokens/src/index.ts) containing CSS variables (--colors-primary-500, --font-families-inter-tight, etc.). These variables are then consumed directly by our UI components and Tailwind CSS.

This process ensures that any change in Figma is systematically propagated through the design tokens to the entire application, maintaining a single, consistent design language.

UI Component Strategy

Aruuri's UI component strategy combines powerful, accessible primitives with a flexible theming and styling approach:

• Radix UI: We utilize Radix UI↗ as the foundation for our interactive components. Radix provides unstyled, accessible, and highly customizable UI primitives that handle complex interactions (e.g., dialogs, dropdowns, tooltips) while allowing full control over styling.
• shadcn/ui v4 Architecture: Our component library builds upon the architecture inspired by shadcn/ui v4. This involves a two-tier component strategy:
  • Base Components (src/components/ui/): These are flat, highly reusable components that wrap Radix primitives and apply Aruuri's specific styling using Tailwind CSS and CVA. They are designed for direct import and composition.
  • Composed Components: Higher-level components that combine multiple base components and encapsulate specific application logic or layouts.
• CVA (Class Variance Authority): CVA↗ is used extensively to manage component variants (e.g., Button with variant="primary" or size="sm"). This allows for type-safe and consistent application of styles based on component props, aligning perfectly with our 1:1 naming principle.
• Tailwind CSS v4: Styling is implemented with Tailwind CSS v4↗. The configuration, found at apps/web/tailwind.config.ts, integrates Aruuri's design tokens directly, ensuring that all Tailwind classes leverage our CSS variables for colors, spacing, and typography. This approach enables rapid UI development while adhering to the design system.

Storybook for Documentation & Testing

Storybook v9↗ serves as the primary workbench for developing, documenting, and testing our UI components.

• Documentation: Every component has dedicated stories that showcase its various states, variants, and use cases (e.g., apps/web/stories/alert.stories.tsx, apps/web/stories/button.stories.tsx). This provides a living style guide and reference for both designers and developers.
• Testing: Storybook is integrated with automated accessibility (a11y) checks, visual regression testing capabilities, and interaction tests to ensure component quality and adherence to specifications.
• Component Definition of Done: To maintain high standards, each UI component must meet a clear "Definition of Done":
  • ✅ Uses design tokens only (no hardcoded values).
  • ✅ Props mirror Figma variants exactly.
  • ✅ Accessibility passes (keyboard navigation, screen reader support, automated checks).
  • ✅ Comprehensive Storybook stories (Playground, various states).
  • ✅ Unit and interaction tests are implemented.
  • ✅ Visual baseline is approved by design.
  • ✅ Changelog entry for any significant updates.

This comprehensive approach to design and development ensures that Aruuri's user interface is not only visually appealing but also robust, maintainable, and accessible for all users.