Design System · Abiir Skin Care

Abiir DS

A complete, production-ready design system grounded in Ayurvedic ritual and Apple-calibre craft. Every token, component, and pattern is documented for both designers and engineers.

⬡

Design Tokens

120+ tokens covering color, typography, spacing, shadows, and motion. JSON-ready for Style Dictionary.

◈

30+ Components

Fully documented with states, anatomy, usage rules, a11y notes, and code specifications.

◉

WCAG 2.1 AA

All components meet contrast, keyboard navigation, and screen reader requirements by default.

System Architecture

The three-layer token model — primitives → semantic aliases → component tokens

Layer 1 · Primitives

saffron-500: #C8813A
space-4: 16px
radius-lg: 12px

Raw values. Never used directly in components.

Layer 2 · Semantic

color-primary: {saffron-500}
color-bg: {neutral-50}
space-component: {space-4}

Intent-based aliases. Change theme here.

Layer 3 · Component

btn-primary-bg: {color-primary}
btn-radius: {radius-full}
btn-padding: {space-4} {space-8}

Component-scoped tokens. Consumed in code.

Stack Compatibility

Designed to work with modern front-end frameworks and tooling

React / Next.js Vue 3 / Nuxt Tailwind CSS CSS Custom Properties Style Dictionary Storybook 7 Figma Variables WCAG 2.1 AA

What's Inside

Navigate using the sidebar — all sections are fully documented and interactive

🎨

Color System

3 full scales, semantic tokens, contrast ratios

Typography

9-level scale, fluid sizing, 2 typefaces

⊞

Spacing & Grid

8px base unit, 12-col grid, responsive rules

⬡

Components

30+ components, all states, code specs

{}

Design Tokens

Full JSON file, Style Dictionary ready

⌨

Dev Handoff

Install, usage, contribution guide

Foundation · 01

Design Principles

Five principles that govern every decision in this system — from macro layout to micro interaction.

Principle 01

Ceremonial Clarity

Every interface moment should feel intentional — like a ritual step, not a transaction. White space is breath between intentions. Favour unhurried layouts over information density.

Principle 02

Botanical Restraint

Like a precision Ayurvedic formula, use only what is needed. No decorative components without function. No animation without meaning. Every pixel earns its place or is removed.

Principle 03

Accessible by Default

WCAG 2.1 AA compliance is the floor, not the ceiling. Focus states are visible and beautiful. All interactions are keyboard-navigable. Screen reader semantics are structural, not bolted on.

Principle 04

Token-First Architecture

No hardcoded values in components. All properties are token-referenced. Theming, dark mode, and brand evolution happen at the token layer — not scattered across component code.

Principle 05

Earned Delight

Micro-interactions and animations exist to orient, not entertain. Delight follows utility — it never precedes it. A button press confirms action; a transition communicates hierarchy.

Dos & Don'ts

✓ Always Do

Use semantic tokens in component code — never primitives directly

Provide visible focus indicators on all interactive elements

Test all new components in both light and dark mode

Use the 8px grid for all spacing decisions

Include loading, error, and empty states in every component

✕ Never Do

Hardcode hex values or pixel sizes in components

Remove focus styles — redesign them instead

Create one-off components outside the system without review

Use color alone to communicate meaning or state

Animate at durations over 400ms without reduced-motion check

Foundation · 02

Design Tokens

The single source of truth. All values are referenced by semantic name — never by raw value in component code.

Token File (JSON)

Style Dictionary compatible. Drop into your build pipeline and generate CSS, iOS, Android, and more.

{
  "color": {
    "primitive": {
      "saffron": {
        "50":  { "value": "#FDF6EC", "type": "color" },
        "100": { "value": "#F7E8CC", "type": "color" },
        "200": { "value": "#EDD298", "type": "color" },
        "300": { "value": "#E2B862", "type": "color" },
        "400": { "value": "#D99B3A", "type": "color" },
        "500": { "value": "#C8813A", "type": "color" },
        "600": { "value": "#A86428", "type": "color" },
        "700": { "value": "#874B1C", "type": "color" },
        "800": { "value": "#6B3614", "type": "color" },
        "900": { "value": "#4A230C", "type": "color" }
      },
      "forest": {
        "50":  { "value": "#EAF0EA" },
        "500": { "value": "#2C4A2E" },
        "600": { "value": "#203822" }
      },
      "neutral": {
        "0":   { "value": "#FFFFFF" },
        "50":  { "value": "#F9F3E8" },
        "100": { "value": "#F0E8D8" },
        "200": { "value": "#DDD0BB" },
        "500": { "value": "#8C7B6A" },
        "600": { "value": "#6B6560" },
        "900": { "value": "#1C1C1A" }
      }
    },
    "semantic": {
      "primary":          { "value": "{color.primitive.saffron.500}" },
      "secondary":        { "value": "{color.primitive.forest.500}"  },
      "background":       { "value": "{color.primitive.neutral.50}"  },
      "surface":          { "value": "{color.primitive.neutral.0}"   },
      "text": {
        "primary":        { "value": "{color.primitive.neutral.900}" },
        "secondary":      { "value": "{color.primitive.neutral.600}" },
        "disabled":       { "value": "{color.primitive.neutral.400}" }
      },
      "border":           { "value": "{color.primitive.neutral.200}" },
      "success":          { "value": "#2D6E3E" },
      "warning":          { "value": "#B87A1A" },
      "error":            { "value": "#C0392B" },
      "info":             { "value": "#1A5C8C" }
    }
  },
  "spacing": {
    "1":  { "value": "4px",  "type": "spacing" },
    "2":  { "value": "8px",  "type": "spacing" },
    "3":  { "value": "12px", "type": "spacing" },
    "4":  { "value": "16px", "type": "spacing" },
    "6":  { "value": "24px", "type": "spacing" },
    "8":  { "value": "32px", "type": "spacing" },
    "12": { "value": "48px", "type": "spacing" },
    "16": { "value": "64px", "type": "spacing" },
    "20": { "value": "80px", "type": "spacing" }
  },
  "typography": {
    "fontFamily": {
      "display": { "value": "'Cormorant Garamond', Georgia, serif"   },
      "body":    { "value": "'Jost', system-ui, sans-serif"          },
      "mono":    { "value": "'JetBrains Mono', 'Courier New', monospace" }
    },
    "fontSize": {
      "xs":   { "value": "0.625rem" }, "sm":   { "value": "0.75rem"  },
      "base": { "value": "0.875rem" }, "md":   { "value": "1rem"     },
      "lg":   { "value": "1.125rem" }, "xl":   { "value": "1.25rem"  },
      "2xl":  { "value": "1.5rem"   }, "4xl":  { "value": "2.75rem"  },
      "5xl":  { "value": "3.75rem"  }
    },
    "fontWeight": {
      "light":   { "value": "300" }, "regular": { "value": "400" },
      "medium":  { "value": "500" }, "semibold":{ "value": "600" }
    },
    "lineHeight": {
      "tight":   { "value": "1.15" }, "normal":  { "value": "1.6"  },
      "relaxed": { "value": "1.8"  }
    }
  },
  "borderRadius": {
    "sm":   { "value": "4px"     }, "md":   { "value": "8px"     },
    "lg":   { "value": "12px"    }, "xl":   { "value": "16px"    },
    "2xl":  { "value": "24px"    }, "full": { "value": "9999px" }
  },
  "shadow": {
    "sm": { "value": "0 1px 2px rgba(28,28,26,0.06)"    },
    "md": { "value": "0 4px 12px rgba(28,28,26,0.08)"   },
    "lg": { "value": "0 8px 24px rgba(28,28,26,0.10)"   },
    "xl": { "value": "0 16px 48px rgba(28,28,26,0.12)"  }
  },
  "motion": {
    "duration": {
      "fast":   { "value": "120ms" }, "base":   { "value": "200ms" },
      "slow":   { "value": "300ms" }, "spring": { "value": "400ms" }
    },
    "easing": {
      "standard": { "value": "cubic-bezier(0.4, 0, 0.2, 1)"      },
      "spring":   { "value": "cubic-bezier(0.34, 1.56, 0.64, 1)" },
      "exit":     { "value": "cubic-bezier(0.4, 0, 1, 1)"         }
    }
  }
}

Live Token Reference

Token NameValuePreview

--color-primary#C8813A (saffron-500)

--color-secondary#2C4A2E (forest-500)

--color-bg#F9F3E8 (neutral-50)

--color-surface#FFFFFF (neutral-0)

--color-text-primary#1C1C1A (neutral-900)

--color-text-secondary#6B6560 (neutral-600)

--color-border#DDD0BB (neutral-200)

--font-displayCormorant Garamond

--space-416px (base × 2)

--radius-lg12px

--shadow-md0 4px 12px rgba(28,28,26,0.08)

--transition-base200ms ease

—

Foundation · 03

Color System

A palette drawn from Ayurvedic botanicals. Three full scales, semantic aliases, and seven contrast-verified pairings.

Saffron — Primary Brand Scale

10 stops from 50–900. Saffron-500 is the primary action color across all interfaces.

#FDF6EC

100

#F7E8CC

200

#EDD298

300

#E2B862

400

#D99B3A

500 ★

#C8813A

600

#A86428

700

#874B1C

800

#6B3614

900

#4A230C

Forest — Secondary Brand Scale

Botanical depth for secondary actions, success states, and Ayurvedic context.

#EAF0EA

100

#C8D9C8

200

#96BB97

300

#659766

400

#3D6B40

500 ★

#2C4A2E

600

#203822

700

#162718

800

#0E190F

900

#070C08

Neutral — Warm Gray Scale

Ivory-warm neutrals — never clinical white. Neutral-50 is the canvas. Neutral-900 is primary text.

#FFFFFF

50 ★

#F9F3E8

100

#F0E8D8

200

#DDD0BB

300

#C4B39A

400

#A89680

500

#8C7B6A

600

#6B6560

700

#4A4540

800

#2E2A26

900

#1C1C1A

Contrast Ratios — WCAG 2.1

AA requires 4.5:1 for normal text, 3:1 for large text and UI components. AAA requires 7:1.

White on Saffron-700

Text on saffron backgrounds

6.8:1

AA ✓

Ivory on Charcoal

Dark mode primary text

15.3:1

AAA ✓

Charcoal on Ivory

Primary body text

15.3:1

AAA ✓

Neutral-600 on Ivory

Secondary body text

4.8:1

AA ✓

White on Forest-500

Secondary button text

8.4:1

AAA ✓

White on Saffron-500

Primary button — large text only

3.1:1

AA Large

Neutral-400 on Ivory

Placeholder / decorative only

2.4:1

Decorative

Semantic Color Palette

SUCCESS

#2D6E3E

WARNING

#B87A1A

ERROR

#C0392B

INFO

#1A5C8C

Foundation · 04

Typography

A 9-level type scale with fluid responsive behavior. Two typefaces — one ceremonial, one precise. Zero compromise on readability.

Type Scale — 9 Levels

All sizes in rem (base 16px). Display and heading sizes use CSS clamp() for fluid scaling.

Level	Token	rem	px	Weight	Leading	Sample
Display	text-5xl	3.75	60	300	1.1	Ritual
H1	text-4xl	2.75	44	300	1.15	Botanical Elixir
H2	text-3xl	2.00	32	300	1.2	Saffron & Sandalwood
H3	text-2xl	1.50	24	400	1.3	Pitta Balance Formula
H4	text-xl	1.25	20	500	1.35	Ingredient Sourcing
Body LG	text-lg	1.125	18	300	1.7	Formulated with cold-pressed botanicals
Body	text-base	0.875	14	300	1.8	Standard body copy and UI text
Small	text-sm	0.75	12	400	1.6	Labels, captions, helper text
XS	text-xs	0.625	10	600	1.5	EYEBROW · LABEL · TAG

Typeface Pairing

Display Face

Cormorant Garamond

Ancient
Wisdom

Use for: headings, product names, pull quotes, packaging
Weights: 300 (primary), 400, 500
Italic: always available and encouraged
Sanskrit terms always in italic 400

Body Face

Jost

Modern
Precision

Use for: body copy, UI labels, navigation, CTAs, data
Weights: 300 (body), 400 (UI), 500 (emphasis), 600 (labels)
Tracking: 0 for body, +0.15em for uppercase labels
No italic usage in Jost

Responsive Sizing

/* Fluid display heading — scales 2.75rem → 3.75rem between 375px → 1280px */
.display {
  font-size: clamp(2.75rem, 1.8vw + 2rem, 3.75rem);
  font-family: var(--font-display);
  font-weight: 300;
  line-height: var(--leading-tight);
}

/* H1 — scales 2rem → 2.75rem */
h1 { font-size: clamp(2rem, 1.5vw + 1.5rem, 2.75rem); }

/* H2 — scales 1.5rem → 2rem */
h2 { font-size: clamp(1.5rem, 1.2vw + 1rem, 2rem); }

/* Body text — fixed, never fluid */
body { font-size: var(--text-base); } /* 0.875rem always */

Foundation · 05

Spacing & Grid

An 8px base unit with a multiplier scale. A 12-column grid with 24px gutters. Every layout decision traceable to a single unit.

8px Spacing Scale

Every spacing value is a multiple of 4px. The 8px base unit creates the visual rhythm.

4px
space-1

8px
space-2

12px
space-3

16px
space-4

20px
space-5

24px
space-6

32px
space-8

40px
space-10

48px
space-12

64px
space-16

80px
space-20

96px
space-24

12-Column Grid

Max-width 1280px · 24px gutters desktop · 16px mobile · 40px+ page margins

12 cols · Full width hero

8 col · Main content

4 col · Sidebar

4 col

4 col · 3-up

3 · 4-up

Mobile (<768px)4 columns · 16px gutter · 16px margin

Tablet (768–1024px)8 columns · 20px gutter · 24px margin

Desktop (>1024px)12 columns · 24px gutter · 40px+ margin

Spacing Usage Rules

Component Internal

Padding: space-3 (12px) to space-6 (24px)
Gap between elements: space-2 to space-4
Icon-to-label gap: space-2 (8px)

Layout Sections

Section padding desktop: space-20 (80px)
Section padding mobile: space-12 (48px)
Between sections: space-16 (64px)

Typography Rhythm

Heading → body: space-4 (16px)
Paragraph gap: space-4 (16px)
Section label → heading: space-2 (8px)

Foundation · 06

Iconography

A restrained icon vocabulary — botanical, minimal, and purposeful. Icons communicate action and state, never decoration alone.

Icon Grid & Sizing

All icons on a 24px grid. Available at 16px, 20px, 24px, and 32px. Stroke: 1.5px currentColor.

Wishlist

Cart

User

Check

Info

Trust

Location

Clock

/* Icon sizing system */
.icon-sm  { width: 16px; height: 16px; } /* Inline / compact UI  */
.icon-md  { width: 20px; height: 20px; } /* Standard buttons      */
.icon-lg  { width: 24px; height: 24px; } /* Navigation, standalone*/
.icon-xl  { width: 32px; height: 32px; } /* Feature / hero icons  */

/* Always inherit colour from text */
svg { stroke: currentColor; stroke-width: 1.5px; fill: none; }

Components · 01

Buttons

6 variants · 3 sizes · 5 states. Every button carries meaning — variant choice communicates action hierarchy.

All Variants

Sizes

Icon Buttons

With Icon

Usage Hierarchy

Token	Usage	Max per view
btn-primary	Single primary CTA. "Add to Cart", "Checkout", "Begin Ritual"	1
btn-secondary	Supporting actions. "View Details", "Learn More"	2–3
btn-outline	Tertiary actions on light bg. "Save", "Compare", "Share"	Unlimited
btn-ghost	Least emphasis. Cancel, dismiss, inline text links	Unlimited

Code Specification

/* Button base — all variants extend this */
.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-2);
  font-family: var(--font-body);
  font-size: var(--text-sm);
  font-weight: 500;
  letter-spacing: var(--tracking-wide);
  text-transform: uppercase;
  border: none;
  cursor: pointer;
  transition: all var(--transition-base);
  border-radius: var(--radius-full);
  line-height: 1;
}

/* Focus — always visible, never removed */
.btn:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 3px;
}

/* Reduced motion — strip all transforms */
@media (prefers-reduced-motion: reduce) {
  .btn { transition: none; transform: none !important; }
}

Components · 02

Form Elements

11 form components. All states documented. All WCAG 2.1 AA compliant with visible focus rings and proper error patterns.

Text Input

States: Default · Focus · Error · Disabled

Email Address We'll send your ritual guide here

Email (Error) Please enter a valid email address

Email (Disabled)

Selection Controls

Checkbox · Radio · Toggle

Subscribe to ritual calendar

Receive ingredient sourcing updates

Vata constitution

Pitta constitution

Morning ritual reminders

SMS notifications

Select & Textarea

Your Dosha Type

Ritual Notes

Tags & Chips

Skin Concerns

Dryness Uneven tone Sensitivity Oiliness Fine lines Pigmentation

With Remove Action

Saffron × Ashwagandha × Neem ×

Quantity Stepper

Components · 03

Navigation

Navbar, breadcrumb, tabs, stepper, and accordion. Navigation carries users through the ritual — it should never interrupt it.

Navbar

Breadcrumb

Tabs

A Pitta-balancing facial elixir formulated with cold-pressed saffron, wild turmeric, and rose hip oil. Clinically shown to reduce inflammation markers by 34% in 8 weeks of use.

Key actives: Crocus sativus (Saffron) 0.02%, Curcuma aromatica (Wild Turmeric) 2%, Rosa canina (Rose Hip) oil 5%, Centella asiatica extract 3%, Sesame oil base.

Apply 3–4 drops to clean, damp skin. Press gently using the Abhyanga method. Use morning and evening. Best after Abiir Cleansing Oil. Suitable for Pitta and Vata constitutions.

★★★★★ 4.8/5 from 312 verified reviews. "My Pitta skin has never felt this calm. The glow develops over days, not hours." — Verified buyer, San Francisco.

Progress Stepper

✓

Dosha Quiz

✓

Ritual Build

Checkout

Confirm

Accordion

What is my Dosha type?+

Dosha is your Ayurvedic constitution — the unique combination of Vata (air/ether), Pitta (fire/water), and Kapha (earth/water) energies that govern your physiology and skin type. Take our 5-minute Dosha quiz to discover yours.

Are Abiir products clinically tested?+

Yes. All Abiir formulations are validated through independent DERMSCAN testing in conjunction with Ayurvedic efficacy protocols. Clinical data is available on each individual product page.

What is your returns policy?+

We offer a 30-day Ritual Guarantee. If your skin does not respond to your formulation within 30 days, we will reformulate your ritual or offer a full refund — no questions asked.

Components · 04

Feedback

Alerts, toasts, progress bars, skeletons, tooltips, and ratings. Every state communicates clearly — without alarm.

Alert Banners

✓

Ritual started

Your Vata Restore morning ritual has been saved to your profile.

⚠

Low stock

Only 3 units of Saffron Elixir remain. Restocking takes 4–6 weeks.

Payment declined

Your card was declined. Please check your details or try another payment method.

Dosha insight

Vata skin benefits most from oil-based formulas applied to slightly damp skin. Learn about your Prakriti.

Toast Notification

Added to your ritual cart View Cart

Progress Bars

Skin hydration score78%

Ritual completion3 of 4 steps

Checkout progressStep 2 of 3

Skeleton Loaders

Tooltip & Rating

4.8 · 312 reviews

Components · 05

Data Display

Avatars, badges, dividers, modals, and cards. Components that present information with the same care as the products they represent.

Avatars

Badges

Bestseller New Formula Vata · Pitta In Stock Sold Out Low Stock Clinical Grade

Dividers

Content above

Content below

or continue with

Content after labeled divider

Modal

Components · 06

Brand-Specific

Components unique to Abiir — Dosha Selector, Product Card, Ingredient Card. These encode the brand's Ayurvedic intelligence into UI structure.

Product Cards

Bestseller

Pitta Balance

Saffron Brightening Elixir

30ml · Cold-pressed · Clinically validated

$94

New

Vata Restore

Ashwagandha Night Balm

50ml · Adaptogenic · Ceramide-rich

$78

Dosha Selector

Select your Dosha constitution

Vata

Air · Ether

Pitta

Fire · Water

Kapha

Earth · Water

Not sure of your constitution? Take the Dosha quiz →

Ingredient Cards

Adaptogen

Ashwagandha

Withania somnifera

Reduces cortisol-driven inflammation. Strengthens skin barrier. Vata-pacifying.

Vata Kapha

Brightener

Saffron

Crocus sativus

Inhibits melanin synthesis. Antioxidant-rich. Sacred in Ayurvedic tradition for 5,000 years.

Pitta Vata

Guidelines · 01

Accessibility

WCAG 2.1 AA compliance is built into the system architecture — not retrofitted. Every component is testable against these specifications.

Focus Management

All interactive elements have visible focus rings. Tab order follows visual reading order. Modal traps focus until dismissed. Skip navigation link on all pages.

:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 3px;
  border-radius: inherit;
}

ARIA Labels

All icon-only buttons have aria-label. Form inputs have associated labels. Error messages linked with aria-describedby. Live regions for dynamic content.

<button aria-label="Add to wishlist">
  <HeartIcon />
</button>

<input aria-invalid="true"
  aria-describedby="email-error"/>

Reduced Motion

/* All transitions respect user preference */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* Apply motion only when safe */
@media (prefers-reduced-motion: no-preference) {
  .btn-primary:hover { transform: translateY(-1px); }
  .product-card:hover { transform: translateY(-2px); }
}

Semantic HTML Requirements

Heading Hierarchy

One h1 per page. Headings descend sequentially (h1→h2→h3). Never use headings for styling — use p with classes instead.

Landmark Regions

Use header, nav, main, aside, footer. Every page must have exactly one main landmark. Navigation must be a nav element with aria-label.

Color Independence

Never use color alone to convey state or meaning. Error states require icon + text + color. Success states require ✓ icon + label.

Guidelines · 02

Design Patterns

Recurring UX patterns across Abiir's digital experiences. Use patterns consistently — do not reinvent them locally.

Pattern 01

Ritual Checkout Flow

The purchase flow is framed as "building a ritual" not "buying products." Use the Progress Stepper component. Steps: (1) Dosha selection → (2) Ritual curation → (3) Personalisation → (4) Checkout. The Dosha Selector always appears before any product selection.

StepperDosha SelectorProduct CardsProgress Bar

Pattern 02

Empty States

✦

Your ritual is empty

Every Ayurvedic journey begins with knowing your constitution. Take the Dosha quiz to build your ritual.

Rule: empty states always provide a primary action. Use display typeface for the empty state headline. Never show a blank screen without direction.

Pattern 03

Loading States

Under 400ms: no indicator. 400ms–3s: skeleton loaders matching the content layout. Over 3s: progress bar with estimated time. For form submission: button enters loading state with spinner. Never block the entire UI for a single async operation.

Button loading state

Skeleton loader

Pattern 04

Error Recovery

Errors are always explanatory and actionable. Error Alert must include: (1) what went wrong, (2) why it happened, (3) how to resolve it. For form errors, focus moves to the first invalid field on submit. Error messages are persistent — never auto-dismiss errors. Every error must have a resolution path visible without additional action.

Guidelines · 03

Developer Handoff

Everything an engineer needs to implement this system correctly — from installation to contribution guidelines.

Installation

# Install the Abiir Design System package
npm install @abiir/design-system

# Or with Yarn
yarn add @abiir/design-system

# Or with pnpm
pnpm add @abiir/design-system

Setup in Next.js / React

// app/layout.tsx
import '@abiir/design-system/styles/tokens.css';
import '@abiir/design-system/styles/globals.css';
import { AbiirProvider } from '@abiir/design-system';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AbiirProvider>
          {children}
        </AbiirProvider>
      </body>
    </html>
  );
}

Component Usage

import {
  Button,
  Input,
  ProductCard,
  DoshaSelector,
  Alert,
  Toast,
  Progress
} from '@abiir/design-system';

// Primary button
<Button variant="primary" size="md" onClick={handleAdd}>
  Add to Ritual
</Button>

// Form input with validation
<Input
  label="Email Address"
  type="email"
  hint="Your ritual guide arrives here"
  error={errors.email}
  value={value}
  onChange={setValue}
/>

// Dosha selector (brand-specific)
<DoshaSelector
  value={selectedDosha}
  onChange={setDosha}
  showQuizLink
/>

// Product card
<ProductCard
  name="Saffron Brightening Elixir"
  dosha="pitta"
  price={94}
  badge="Bestseller"
  onAddToCart={handleAdd}
/>

CSS Custom Properties Usage

/* Consume tokens directly in custom CSS */
.custom-hero {
  background:     var(--color-bg);
  padding:        var(--space-20) var(--space-8);
  font-family:    var(--font-display);
  border-radius:  var(--radius-2xl);
  box-shadow:     var(--shadow-lg);
}

/* NEVER hardcode values — always reference tokens */
.wrong { color: #C8813A; }             /* ✕ Breaks theming */
.right { color: var(--color-primary); } /* ✓ Token-referenced */

/* Responsive custom component */
.custom-grid {
  display: grid;
  grid-template-columns: repeat(12, 1fr);
  gap: var(--space-6);
  max-width: 1280px;
  margin: 0 auto;
  padding: 0 var(--space-8);
}

File Structure

@abiir/design-system/
├── styles/
│   ├── tokens.css          # All CSS custom properties
│   ├── globals.css         # Reset + base styles
│   └── typography.css      # Type scale utilities
├── tokens/
│   ├── abiir.tokens.json   # Style Dictionary source
│   └── dark.tokens.json    # Dark mode overrides
├── components/
│   ├── Button/             # Button.tsx + Button.test.tsx
│   ├── Input/              # Input.tsx + Input.stories.tsx
│   ├── ProductCard/        # Abiir-specific component
│   ├── DoshaSelector/      # Abiir-specific component
│   ├── IngredientCard/     # Abiir-specific component
│   ├── Alert/
│   ├── Toast/
│   ├── Progress/
│   ├── Accordion/
│   ├── Tabs/
│   ├── Modal/
│   ├── Skeleton/
│   ├── Rating/
│   ├── Stepper/
│   ├── Badge/
│   ├── Avatar/
│   └── ...                 # 30+ total components
├── hooks/
│   ├── useDosha.ts
│   └── useRitual.ts
└── docs/
    └── storybook/          # Component stories

Contribution Protocol

Adding a Component

1. Propose in design system Slack channel
2. Design review with design lead
3. Implement with TypeScript + tests
4. Document all props + states in Storybook
5. Pass a11y audit (axe-core)
6. PR review from 2 engineers
7. Release in minor version bump

Modifying a Token

1. Tokens are versioned — changes require CHANGELOG entry
2. Primitive token changes require full contrast re-audit
3. Semantic token changes require component regression test
4. Notify all teams consuming the token in advance
5. Deprecate old token for 2 versions before removal

Abiir Design System

Version 1.0.0 · WCAG 2.1 AA · Style Dictionary Compatible
30+ Components · 120+ Tokens · 3-Layer Architecture
Built for Abiir Skin Care · Where Ancient Wisdom Meets Modern Skin

Abiir DS

Design Principles

Design Tokens

Color System

Typography

Spacing & Grid

Iconography

Buttons

Form Elements

Navigation

Feedback

Data Display

Brand-Specific

Accessibility

Design Patterns

Developer Handoff

CHINMAY LAGHATE