Theming & Customization
Learn how to re-skin `@a11ypros/a11y-ui-components` to match your company's brand, design system, and aesthetic using our 3-tier CSS Custom Property architecture.
Live Theme Studio
Customize the tokens below to preview the changes in real-time across multiple components, then copy the generated CSS tokens into your application.
Accessible Accordion Item 1
Accessible Accordion Item 2
Active tab underline and text color match your primary brand color.
:root {
/* Brand Colors */
--a11y-color-primary: #0369a1;
--a11y-color-primary-hover: #075985;
/* Corner Radius Scale */
--a11y-radius: 0.375rem;
/* Typography */
--a11y-font-sans: inherit;
}The 3-Tier Theming Architecture
Our components are built with standard CSS Custom Properties organized in three tiers so you can customize at whatever level of granularity you need:
Tier 1: Global Brand Tokens (--a11y-*)
Define these on :root or a container element. They cascade down to all components automatically. Adjusting --a11y-color-primary or --a11y-radius instantly re-skins the entire library.
Tier 2: Component-Scoped Tokens (--btn-*, --input-*, etc.)
Target specific component types without affecting others. For example, set .btn { --btn-radius: 9999px; } to make buttons pill-shaped while keeping inputs standard rounded.
Tier 3: Instance & Tailwind Overrides
Pass inline style props or Tailwind className utilities directly to component instances for one-off tweaks.
Global Token Reference
| Token | Default (Light) | Description |
|---|---|---|
--a11y-color-primary | #0369a1 | Main brand color used for primary buttons, active tabs, check states. |
--a11y-color-primary-hover | #075985 | Darker shade for hover interactions. |
--a11y-color-primary-fg | #ffffff | Foreground text color on primary backgrounds (ensures contrast). |
--a11y-radius | 0.375rem (6px) | Universal base corner radius for buttons, inputs, tables, fieldsets. |
--a11y-radius-lg | 0.5rem (8px) | Larger corner radius for modals, banners, accordions. |
--a11y-color-focus | #0ea5e9 | Focus visible ring color (WCAG 2.4.7 / 2.4.11 compliant). |
--a11y-focus-width | 2px | Thickness of the keyboard focus ring. |
--a11y-font-sans | System font stack | Primary font family for all UI components. |
Component-Scoped Variables
| Component | Available Custom Properties |
|---|---|
| Button | --btn-radius, --btn-primary-bg, --btn-primary-fg, --btn-secondary-bg, --btn-danger-bg, --btn-font-family |
| Input / Textarea / Select | --input-bg, --input-color, --input-border-color, --input-radius, --input-focus-border, --input-focus-ring |
| Modal | --modal-bg, --modal-radius, --modal-shadow, --modal-backdrop-bg, --modal-border-color |
| Banner | --banner-radius, --banner-info-bg, --banner-info-border, --banner-success-bg, --banner-warning-bg, --banner-error-bg |
| Tabs | --tabs-active-color, --tabs-active-border-color, --tabs-border-color |
| Accordion | --accordion-bg, --accordion-radius, --accordion-header-hover-bg |
| DataTable | --table-radius, --table-border-color, --table-header-bg, --table-row-hover-bg, --table-selected-bg |
WCAG Color Contrast & Accessibility Requirements
While @a11ypros/a11y-ui-components comes with fully accessible defaults, overriding design tokens with your own custom brand palette requires adhering to WCAG 2.1 Level AA color contrast requirements:
| Element Type | WCAG Criterion | Minimum Contrast Ratio | Description & Scope |
|---|---|---|---|
| Body & UI Text | 1.4.3 Contrast (Minimum) | 4.5:1 (Level AA) | Applies to all normal body copy, button labels, input placeholders, tabs, and table cell content. |
| Large Text | 1.4.3 Contrast (Minimum) | 3:1 (Level AA) | Applies to large text at or above 18pt (24px) or bold text at or above 14pt (18.66px). |
| Interactive Elements & UI Components | 1.4.11 Non-text Contrast | 3:1 (Level AA) | Applies to interactive component borders (input outlines, checkboxes, radios), icons, and state boundaries. |
| Focus Rings & Indicators | 2.4.11 Focus Appearance | 3:1 (Level AA) | Ensure --a11y-color-focus has at least 3:1 contrast against adjacent background colors. |
Scoped / Multi-Tenant Theming
Because our theming uses standard CSS custom properties, you can create multi-tenant or section-specific themes simply by applying a CSS class:
/* globals.css */
.tenant-marketing {
--a11y-color-primary: #8b5cf6; /* Purple */
--a11y-radius: 9999px; /* Pill buttons */
}
.tenant-dashboard {
--a11y-color-primary: #0284c7; /* Sky */
--a11y-radius: 4px; /* Subtle corners */
}