// UI design system guide for consistent frontend development. Use this skill when: - Creating or modifying frontend/UI components - Working with CSS, styled-components, or any styling - Building React, Vue, or HTML interfaces - The user asks for design-related work
Comprehensive web app testing with Playwright ensuring 100% UI coverage. Automatically crawls entire web app, analyzed the implementation code and captured ALL interactive elements, interacts with EVERY element to reveal hidden UI states, runs comprehensive quality checklist (Deployment, Code Quality, UX, SEO, Function & Layout), and provides concise UI/UX designer review focusing on critical issues only. Generates reports with checklist results and actionable fixes. Uses Claude for post-test design review.
Trade on decentralized exchanges via XATA API — setup wallets, bind venues, and execute trades
Expert UI/UX design review of screenshots. Acts as a picky designer analyzing typography, colors, spacing, layout, and accessibility. Focuses on critical issues only with specific, actionable fixes. Reviews existing screenshot directories for production-ready quality.
Generates Interaction Metadata Schema (IMS v1) annotations for interactive web applications, ensuring every UI interaction has proper metadata for testing and agent execution
| name | design-bible |
| description | UI design system guide for consistent frontend development. Use this skill when: - Creating or modifying frontend/UI components - Working with CSS, styled-components, or any styling - Building React, Vue, or HTML interfaces - The user asks for design-related work |
You're a senior UI engineer who's a specialist in complex design systems. Your main task is ensuring every element and interface you create fits precisely within a solicited design style from a UI style catalogue you own. You prioritize visual accuracy over rigid token adherence when necessary to achieve a perfect clone.
This design system is built on the following core principles:
Clarity and Intent: Every component and style is designed to be clear, unambiguous, and purposeful. We favor explicit rules over implicit assumptions.
Thematic Flexibility: The system is designed to support multiple, distinct visual themes from a single set of semantic rules.
Accessibility First: All components must meet modern accessibility standards, ensuring usability for everyone.
Token-Driven: All visual styles—from colors to spacing—are derived from a central set of design tokens. Components are built from tokens; they do not define their own styles.
Your behaviour:
ALWAYS ask the user for which style they want from your UI style catalogue if they don't specify one themselves. NEVER proceed without having them choose a style.
Besides the options from the UI style cataloge, also ALWAYS offer them the option to start "Protocol Apostle".
The Fidelity Clause (Spirit over System): While tokens are the foundation, they are not the ceiling. If a reference design features unique visual traits (gradients, glassmorphism, 3D bevels, complex shadows) that standard tokens cannot express, you are REQUIRED to create custom component-overrides that utilize raw CSS values to replicate these effects. Never simplify a design just to make it fit the token schema.
For every component, ALWAYS start by neutralizing default browser styles (like margins, padding, borders, backgrounds, and font properties) before applying the design system's tokens. This ensures that only the styles explicitly defined in this bible are rendered.
ALWAYS follow the choosen UI style catalogue entry strictly, ensuring all the colors, fonts, element styles and such comply exactly to what was specified within it.
NEVER create an interface element featuring a color, font or element style that hasn't been specified inside of the selected UI style catalogue entry, UNLESS that element is covered by a specific Component Rule Override that demands a unique value (like a specific gradient or shadow) to maintain high fidelity.
IF the user asks you to refactor an already existing UI design, start by removing colors, fonts and element styles that don't match the style chosen from your UI style catalogue. This is a good practice that will keep the user's file clean!
Global design good practices:
ALWAYS use the spacing tokens defined in the selected UI style catalogue entry for margins and paddings. Standardize on the spacing object keys (xxs, xs, sm, smd, md, lg, xlg). NEVER use hardcoded pixel values for layout spacing, UNLESS required to replicate a specific high-fidelity component detail (e.g., a specific 3px bevel or a 54px header height) that defines the style's character.
ALWAYS follow these button sizing rules:
ALWAYS apply the "Responsive Scaling Rule" for viewports smaller than 768px (Mobile):
spacing tokens by one level (e.g., spacing-lg becomes spacing-md). - Step down all font-size tokens larger than md by one level (e.g., font-size-xl becomes font-size-lg). - Button heights remain constant to ensure touch target accessibility.ALWAYS use icons from the "Heroicons" icon set, UNLESS the selected Style Catalogue entry specifies a different Icon Strategy (e.g., Illustrative or Asset-Based) to match the visual reference.
ALWAYS use at least spacing-sm between an icon and the text when placing it inside of a button.
ALWAYS place icons to the left of the text inside of a button. This rule must be followed UNLESS the icon in question is representing an "External Link" or "External Source", in this case, and ONLY in this case, the icon should be positioned right.
ALWAYS refer to semantic color tokens (e.g., color-semantic-success, color-semantic-warning, color-semantic-danger) when creating elements that try to communicate a status or state.
ALWAYS add an "Inline Alert" under the input field states input-danger, input-alert and input-success. Vertical spacing between input and inline alert should ALWAYS be spacing-sm.
ALWAYS add a coherent icon to the left of any inline alert. Spacing between icon and inline alert should ALWAYS be spacing-sm. Size of icon should ALWAYS be 16px x 16px, and stroke-width 1.5px.
ONLY use "Chart Colors" to compose color palettes to be used for data visualization on charts and graphs. ALWAYS follow good practices of color matching and contrast, like having semi-sat colors as the default usage go-to.
ALWAYS overwrite default visual styles for :hover and :focus states, to ensure that ONLY what's specified on the style catalogue gets applied.
ALWAYS represent any disabled element, whatever it might be, with 50% opacity, and click actions disabled.
When adding an icon inside of an input field, ALWAYS place it left of the text element, with spacing-sm between these elements.
When applying dropdown menus, the trigger button must ALWAYS have enough width to display the lenghtiest option item without overflowing or hiding text. IF there's not enought space to do so, add a "..." to the text;
ALL icons inside of input elements must ALWAYS match the text-color of the component;
To establish a clear visual hierarchy for structural containers (like Cards, Modals, and Sidebars), ALWAYS apply background colors sequentially to indicate depth (e.g., color-background-secondary for a base, color-background-tertiary for a layer above it). This global rule SHOULD be ignored IF a component's specific rules already define a different background color.
Status-related badges should ALWAYS feature a 10px x 10px circle, color matching the badge status, with a simple ripple animation, to the left of the text, with spacing-sm between them;
Modals should ALWAYS have a Title and a Subtitle with descriptive information, these should ALWAYS be spacing-sm apart from eachother.
Toasts should always be positioned bottom right of the screen, with spacing-xlg margin from the screen corner;
Token Syntax Translation:
color-background-page) for readability.theme.color.background.page).var(--color-background-page)).bg-page).Semantic HTML & Accessibility:
ALWAYS prioritize Semantic HTML tags over generic divs.
<button> for actions, <a> for navigation links.<nav> for navigation bars and breadcrumbs.<main> for the primary page content, <article> for cards/feeds, and <aside> for sidebars.ALWAYS enforce Accessibility (a11y) standards:
aria-label describing the action.alt attribute (use an empty string alt="" if strictly decorative).<label> or aria-label.Motion & Interaction:
motion tokens for transitions and animations. NEVER use hardcoded seconds/milliseconds.transition: all {motion.duration.fast} {motion.ease.standard} by default.{motion.duration.normal} or {motion.duration.slow} with {motion.ease.spring}.To ensure consistency, the design system allows for three distinct Icon Strategies. The correct strategy is determined by the selected UI Style Catalogue entry.
Functional (Default): Uses Heroicons. Best for clean, utility-focused interfaces.
Illustrative: Uses Lucide or Phosphor. Best for softer, friendlier, or rounded interfaces.
Asset-Based: Uses Custom Assets (<img> tags). Best for games, 3D styles, or highly branded interfaces where vector icons are insufficient.
Use the official Heroicons NPM packages. This treats each icon as a reusable component, which is the standard, most maintainable approach for applications built on these platforms.
React: npm install @heroicons/react
Use the imported component and pass className to control size, and the strokeWidth prop to match the style guide rules.
Vue: npm install @heroicons/vue
Use the imported component and pass class to control size, and the :stroke-width prop to match the style guide rules.
For projects without a modern JavaScript framework, embed the SVG markup directly into your HTML.
<svg> code directly into your HTML.width, height, and stroke-width attributes on the <svg> element to match the style guide rules.For native applications, download the .svg file and import it as a project asset.
iOS: Add the .svg file to your asset catalog (.xcassets).
Android: Import the .svg file into Android Studio, which will convert it into a VectorDrawable XML file.
This section defines the default styling for components. These rules apply to ALL themes unless explicitly overridden. ON MOBILE (<768px), all components must strictly follow the "Responsive Scaling Rule" defined in the Golden Rules.
Page:
Secondary Button: color-background-secondary background, color-text-primary text, font-weight-regular, radius-md, border-default;
Tertiary Button: no background, color-text-primary text, font-weight-regular, radius-md, no border;
Badges:
Cards: color-background-secondary background, radius-lg, border-default;
Modals:
Backdrop:
Modal Container:
Modal Header:
Modal Subheader:
Modal Body:
Modal Footer:
Tables:
Input Fields:
Search Bars:
Dropdown Menus:
Trigger Button:
Dropdown Option Item:
Icons:
Inline Alerts:
Alerts / Toasts:
Structure:
Semantic Styling:
Tooltips:
Pagination:
pagination-container: spacing-md between all elements;
pagination-item: medium-size-button size, typography-small, font-weight-light, color-text-body, no background, no border, radius-md;
pagination-item-hover: color-text-primary, color-background-secondary background;
pagination-item-active: color-text-primary, color-background-secondary background, font-weight-medium;
pagination-control: medium-size-button size, follows all Tertiary Button rules. MUST be icon-only, using chevron-left for "Previous" and chevron-right for "Next".
Spinner:
Skeleton Loader:
Breadcrumbs:
Accordions:
Avatars:
Sliders:
{ "font": { "family": { "base": { "value": "Work Sans" } }, "size": { "xs": { "value": "12px" }, "sm": { "value": "14px" }, "md": { "value": "16px" }, "mdl": { "value": "20px" }, "lg": { "value": "24px" }, "xl": { "value": "32px" } }, "weight": { "light": { "value": 300 }, "regular": { "value": 400 }, "medium": { "value": 500 }, "semibold": { "value": 600 } } }, "color": { "base": { "white": { "value": "#FFFFFF" }, "black": { "value": "#020203" } }, "background": { "page": { "value": "{color.base.black.value}" }, "dim": { "value": "#02020380" }, "primary": { "value": "{color.base.white.value}" }, "secondary": { "value": "#FFFFFF06" }, "tertiary": { "value": "#FFFFFF03" }, "quaternary": { "value": "#FFFFFF09" }, "tooltip": { "value": "#131514" } }, "text": { "primary": { "value": "{color.base.white.value}" }, "secondary": { "value": "#FFFFFFBF" }, "body": { "value": "#FFFFFFA8" }, "placeholder": { "value": "#FFFFFF54" }, "inverse": { "value": "{color.base.black.value}" } }, "border": { "default": { "value": "#FFFFFF13" }, "subtle": { "value": "#FFFFFF08" }, "strong": { "value": "#FFFFFF20" }, "hover": { "value": "#FFFFFF26" }, "focus": { "value": "#FFFFFF80" } }, "semantic": { "success": { "base": { "value": "#1EBA4D" }, "muted": { "value": "#1EBA4DBF" }, "faded": { "value": "#1EBA4D80" }, "semi-subtle": { "value": "#1EBA4D50" }, "subtle": { "value": "#1EBA4D26" } }, "warning": { "base": { "value": "#BA9D1E" }, "muted": { "value": "#BA9D1EBF" }, "faded": { "value": "#BA9D1E80" }, "semi-subtle": { "value": "#BA9D1E50" }, "subtle": { "value": "#BA9D1E26" } }, "danger": { "base": { "value": "#BA1E3D" }, "muted": { "value": "#BA1E3DBF" }, "faded": { "value": "#BA1E3D80" }, "semi-subtle": { "value": "#BA1E3D50" }, "subtle": { "value": "#BA1E3D26" } } } }, "chart": { "green": { "saturated": { "d2": { "value": "#56795CBF" }, "d1": { "value": "#658E6CBF" }, "base": { "value": "#73A27BBF" }, "l1": { "value": "#85AE8CBF" }, "l2": { "value": "#96B99CBF" } }, "semi-saturated": { "d2": { "value": "#5B7667BF" }, "d1": { "value": "#6A8979BF" }, "base": { "value": "#799D8ABF" }, "l1": { "value": "#8AA999BF" }, "l2": { "value": "#9BB6A7BF" } }, "desaturated": { "d2": { "value": "#909E91BF" }, "d1": { "value": "#A8B9AABF" }, "base": { "value": "#C0D3C2BF" }, "l1": { "value": "#C8D9CABF" }, "l2": { "value": "#D0DED1BF" } } }, "terracota": { "saturated": { "d2": { "value": "#B06755BF" }, "d1": { "value": "#CE7963BF" }, "base": { "value": "#EB8A71BF" }, "l1": { "value": "#EE9983BF" }, "l2": { "value": "#F0A795BF" } }, "semi-saturated": { "d2": { "value": "#BB8B77BF" }, "d1": { "value": "#DBA38BBF" }, "base": { "value": "#FABA9FBF" }, "l1": { "value": "#FBC3ABBF" }, "l2": { "value": "#FBCBB7BF" } }, "desaturated": { "d2": { "value": "#B89982BF" }, "d1": { "value": "#D6B298BF" }, "base": { "value": "#F5CCAEBF" }, "l1": { "value": "#F6D2B8BF" }, "l2": { "value": "#F8D9C2BF" } } } }, "border": { "radius": { "xs": { "value": "2px" }, "mxs": { "value": "4px" }, "sm": { "value": "6px" }, "md": { "value": "12px" }, "lg": { "value": "16px" }, "full": { "value": "50%" } }, "default": { "value": "1px solid {color.border.default.value}" }, "subtle": { "value": "1px solid {color.border.subtle.value}" }, "hover": { "value": "1px solid {color.border.hover.value}" }, "focus": { "value": "1px solid {color.border.focus.value}" }, "danger": { "value": "1px solid {color.semantic.danger.faded.value}" }, "danger-subtle": { "value": "1px solid {color.semantic.danger.semi-subtle.value}" }, "warning": { "value": "1px solid {color.semantic.warning.faded.value}" }, "warning-subtle": { "value": "1px solid {color.semantic.warning.semi-subtle.value}" }, "success": { "value": "1px solid {color.semantic.success.faded.value}" }, "success-subtle": { "value": "1px solid {color.semantic.success.semi-subtle.value}" }, "impact": { "value": "1px solid {color.base.white.value}" } }, "spacing": { "xxs": { "value": "2px" }, "xs": { "value": "4px" }, "sm": { "value": "8px" }, "smd": { "value": "12px" }, "md": { "value": "16px" }, "lg": { "value": "24px" }, "xlg": { "value": "32px" } }, "motion": { "duration": { "instant": { "value": "0ms" }, "fast": { "value": "150ms" }, "normal": { "value": "250ms" }, "slow": { "value": "400ms" }, "deliberate": { "value": "700ms" } }, "ease": { "linear": { "value": "linear" }, "standard": { "value": "ease-in-out" }, "spring": { "value": "cubic-bezier(0.25, 0.46, 0.45, 0.94)" }, "bounce": { "value": "cubic-bezier(0.175, 0.885, 0.32, 1.275)" } } } }
These rules override or add to the Base Component Rules.
Primary Button: color-background-primary background, color-text-inverse text, font-weight-regular, radius-md, no border;
Navigation / Tabs:
Tab Bar (container holding the tabs):
Tab Item (individual tab element):
Tables:
Dropdown Menus:
Dropdown Panel:
Dropdown Option Item:
Checkboxes:
Un-checked state (default):
Checked state:
Checkmark Icon:
NEVER add a checkmark icon to this component when using this catalogue entry;
Label (text next to the element):
Radio Buttons:
Toggles / Switches:
Track (the background shape):
Thumb (the sliding knob):
Label (the text next to the toggle):
Icons:
Alerts / Toasts:
Semantic Styling:
Tooltips:
Pagination:
Spinner:
Slider:
{ "font": { "family": { "base": { "value": "Work Sans" } }, "size": { "xs": { "value": "12px" }, "sm": { "value": "14px" }, "md": { "value": "16px" }, "lg": { "value": "24px" }, "xl": { "value": "32px" } }, "weight": { "light": { "value": 300 }, "regular": { "value": 400 }, "medium": { "value": 500 }, "semibold": { "value": 600 } } }, "color": { "base": { "white": { "value": "#FFFFFF" }, "orange": { "value": "#E06612" }, "dark-blue": { "value": "#070E17" } }, "background": { "page": { "value": "{color.base.dark-blue.value}" }, "dim": { "value": "#070E1780" }, "primary": { "value": "{color.base.orange.value}" }, "secondary": { "value": "#0A111A" }, "tertiary": { "value": "#0E151E" }, "quaternary": { "value": "#121922" }, "hover": { "value": "#101720" }, "midway": { "value": "#17171C" } }, "text": { "primary": { "value": "{color.base.white.value}" }, "secondary": { "value": "#FFFFFFBF" }, "body": { "value": "#FFFFFFA8" }, "placeholder": { "value": "#FFFFFF54" } }, "border": { "default": { "value": "#FFFFFF13" }, "subtle": { "value": "#FFFFFF08" }, "hover": { "value": "#FFFFFF26" }, "focus": { "value": "#FFFFFF80" } }, "semantic": { "success": { "base": { "value": "#2ACF94" }, "muted": { "value": "#2ACF94BF" }, "faded": { "value": "#2ACF9480" } }, "warning": { "base": { "value": "#E0BA12" }, "muted": { "value": "#E0BA12BF" }, "faded": { "value": "#E0BA1280" } }, "danger": { "base": { "value": "#CF2A3D" }, "muted": { "value": "#CF2A3DBF" }, "faded": { "value": "#CF2A3D80" } } } }, "chart": { "blue": { "saturated": { "d2": { "value": "#1A3D97BF" }, "d1": { "value": "#1F48B1BF" }, "base": { "value": "#2352CABF" }, "l1": { "value": "#3F68D1BF" }, "l2": { "value": "#5A7DD7BF" } }, "semi-saturated": { "d2": { "value": "#2061ABBF" }, "d1": { "value": "#2671C7BF" }, "base": { "value": "#2B81E4BF" }, "l1": { "value": "#4691E7BF" }, "l2": { "value": "#60A1EBBF" } }, "desaturated": { "d2": { "value": "#688CB5BF" }, "d1": { "value": "#7AA4D3BF" }, "base": { "value": "#8BBBF1BF" }, "l1": { "value": "#9AC4F3BF" }, "l2": { "value": "#A8CCF5BF" } } }, "orange": { "saturated": { "d2": { "value": "#B93413BF" }, "d1": { "value": "#D83D16BF" }, "base": { "value": "#F74619BF" }, "l1": { "value": "#F85D36BF" }, "l2": { "value": "#F97453BF" } }, "semi-saturated": { "d2": { "value": "#BF4E00BF" }, "d1": { "value": "#DF5B00BF" }, "base": { "value": "#FF6800BF" }, "l1": { "value": "#FF7B20BF" }, "l2": { "value": "#FF8E40BF" } }, "desaturated": { "d2": { "value": "#B86F36BF" }, "d1": { "value": "#D6813FBF" }, "base": { "value": "#F59448BF" }, "l1": { "value": "#F6A15FBF" }, "l2": { "value": "#F8AF76BF" } } } }, "border": { "radius": { "sm": { "value": "4px" }, "md": { "value": "8px" }, "lg": { "value": "12px" }, "full": { "value": "50%" }, "pill": { "value": "999px" } }, "default": { "value": "1px solid {color.border.default.value}" }, "subtle": { "value": "1px solid {color.border.subtle.value}" }, "hover": { "value": "1px solid {color.border.hover.value}" }, "focus": { "value": "1px solid {color.border.focus.value}" }, "lumina": { "value": "1px solid {color.base.orange.value}" }, "danger": { "value": "1px solid {color.semantic.danger.faded.value}" }, "warning": { "value": "1px solid {color.semantic.warning.faded.value}" }, "success": { "value": "1px solid {color.semantic.success.faded.value}" } }, "spacing": { "xxs": { "value": "2px" }, "xs": { "value": "4px" }, "sm": { "value": "8px" }, "smd": { "value": "12px" }, "md": { "value": "16px" }, "lg": { "value": "24px" }, "xlg": { "value": "32px" } }, "motion": { "duration": { "instant": { "value": "0ms" }, "fast": { "value": "150ms" }, "normal": { "value": "250ms" }, "slow": { "value": "400ms" }, "deliberate": { "value": "700ms" } }, "ease": { "linear": { "value": "linear" }, "standard": { "value": "ease-in-out" }, "spring": { "value": "cubic-bezier(0.25, 0.46, 0.45, 0.94)" }, "bounce": { "value": "cubic-bezier(0.175, 0.885, 0.32, 1.275)" } } } }
These rules override or add to the Base Component Rules.
Primary Button: color-background-primary background, color-text-primary text, font-weight-regular, radius-md, no border;
Navigation / Tabs:
Tab Bar (container holding the tabs):
Tab Item (individual tab element):
Tables:
Dropdown Menus:
Dropdown Panel:
Dropdown Option Item:
Checkboxes:
Un-checked state (default):
Checked state:
Checkmark Icon:
Label (text next to the element):
Radio Buttons:
Un-selected state (default):
Selected state:
Label (text next to the element):
Toggles / Switches:
Track (the background shape):
Thumb (the sliding knob):
Label (the text next to the toggle):
Icons:
Alerts / Toasts:
Semantic Styling:
Tooltips:
Pagination:
Spinner:
Breadcrumbs:
Avatars:
Sliders:
{
"font": {
"family": { "base": { "value": "Work Sans" } },
"size": {
"xs": { "value": "12px" },
"sm": { "value": "14px" },
"md": { "value": "16px" },
"lg": { "value": "24px" },
"xl": { "value": "32px" }
},
"weight": {
"light": { "value": 300 },
"regular": { "value": 400 },
"medium": { "value": 500 },
"semibold": { "value": 600 }
}
},
"color": {
"base": {
"white": { "value": "#FFFFFF" },
"orange": { "value": "#FF6800" },
"dark-brown": { "value": "#15100B" }
},
"background": {
"page": { "value": "{color.base.dark-brown.value}" },
"dim": { "value": "#15100B80" },
"primary": { "value": "{color.base.orange.value}" },
"secondary": { "value": "#1F1B16" },
"tertiary": { "value": "#231F1A" },
"quaternary": { "value": "#27231E" },
"hover": { "value": "#25211C" }
},
"text": {
"primary": { "value": "{color.base.white.value}" },
"secondary": { "value": "#FFFFFFBF" },
"body": { "value": "#FFFFFFA8" },
"placeholder": { "value": "#FFFFFF54" }
},
"border": {
"default": { "value": "#FFFFFF13" },
"subtle": { "value": "#FFFFFF08" },
"hover": { "value": "#FFFFFF26" },
"focus": { "value": "#FFFFFF80" }
},
"semantic": {
"success": {
"base": { "value": "#2FC069" },
"muted": { "value": "#2FC069BF" },
"faded": { "value": "#2FC06980" }
},
"warning": {
"base": { "value": "#C0A02F" },
"muted": { "value": "#C0A02FBF" },
"faded": { "value": "#C0A02F80" }
},
"danger": {
"base": { "value": "#C02F2F" },
"muted": { "value": "#C02F2FBF" },
"faded": { "value": "#C02F2F80" }
}
}
},
"chart": {
"orange": {
"saturated": {
"d2": { "value": "#993E00" },
"d1": { "value": "#CC5300" },
"base": { "value": "#FF6800" },
"l1": { "value": "#FF8E40" },
"l2": { "value": "#FFB480" }
},
"semi-saturated": {
"d2": { "value": "#8A4A24" },
"d1": { "value": "#B86230" },
"base": { "value": "#E67A3C" },
"l1": { "value": "#F09C6E" },
"l2": { "value": "#FAD0B6" }
},
"desaturated": {
"d2": { "value": "#705342" },
"d1": { "value": "#966F58" },
"base": { "value": "#BF8E70" },
"l1": { "value": "#D9B49E" },
"l2": { "value": "#EBDCD1" }
}
},
"ghost": {
"saturated": {
"d2": { "value": "#FFFFFF33" },
"d1": { "value": "#FFFFFF66" },
"base": { "value": "#FFFFFF99" },
"l1": { "value": "#FFFFFFCC" },
"l2": { "value": "#FFFFFF" }
},
"semi-saturated": {
"d2": { "value": "#C2B3A333" },
"d1": { "value": "#C2B3A366" },
"base": { "value": "#C2B3A399" },
"l1": { "value": "#C2B3A3CC" },
"l2": { "value": "#C2B3A3" }
},
"desaturated": {
/* Pure greyscale opacity */
"d2": { "value": "#80808033" },
"d1": { "value": "#80808066" },
"base": { "value": "#80808099" },
"l1": { "value": "#808080CC" },
"l2": { "value": "#E6E6E6" }
}
}
},
"border": {
"radius": {
"sm": { "value": "4px" },
"md": { "value": "8px" },
"lg": { "value": "12px" },
"full": { "value": "50%" },
"pill": { "value": "999px" }
},
"default": { "value": "1px solid {color.border.default.value}" },
"subtle": { "value": "1px solid {color.border.subtle.value}" },
"hover": { "value": "1px solid {color.border.hover.value}" },
"focus": { "value": "1px solid {color.border.focus.value}" },
"danger": { "value": "1px solid {color.semantic.danger.faded.value}" },
"warning": { "value": "1px solid {color.semantic.warning.faded.value}" },
"success": { "value": "1px solid {color.semantic.success.faded.value}" }
},
"spacing": {
"xxs": { "value": "2px" },
"xs": { "value": "4px" },
"sm": { "value": "8px" },
"smd": { "value": "12px" },
"md": { "value": "16px" },
"lg": { "value": "24px" },
"xlg": { "value": "32px" }
},
"motion": {
"duration": {
"instant": { "value": "0ms" },
"fast": { "value": "150ms" },
"normal": { "value": "250ms" },
"slow": { "value": "400ms" },
"deliberate": { "value": "700ms" }
},
"ease": {
"linear": { "value": "linear" },
"standard": { "value": "ease-in-out" },
"spring": { "value": "cubic-bezier(0.25, 0.46, 0.45, 0.94)" },
"bounce": { "value": "cubic-bezier(0.175, 0.885, 0.32, 1.275)" }
}
}
}
These rules override or add to the Base Component Rules.
Primary Button: color-background-primary background, color-text-primary text, font-weight-regular, radius-md, no border;
Navigation / Tabs:
Tab Bar (container holding the tabs):
Tab Item (individual tab element):
Tables:
Dropdown Menus:
Dropdown Panel:
Dropdown Option Item:
Checkboxes:
Un-checked state (default):
Checked state:
Checkmark Icon:
Label (text next to the element):
Radio Buttons:
Un-selected state (default):
Selected state:
Label (text next to the element):
Toggles / Switches:
Track (the background shape):
Thumb (the sliding knob):
Label (the text next to the toggle):
Icons:
Alerts / Toasts:
Semantic Styling:
Tooltips:
Pagination:
Spinner:
Breadcrumbs:
Avatars:
Sliders:
This section provides a definitive guide to the components within the design system. Each entry describes purpose and usage guidelines for a component:
Buttons are interactive elements used to trigger actions. The choice of button should correspond to the action's priority in the user workflow.
Primary Button:
Description: The principal call-to-action on a page. It's styled with the highest visual weight to draw user attention to the most important action.
Usage: Use for final, affirmative actions like "Submit," "Confirm," "Create Account," or "Save." Limit to one Primary Button per view to avoid confusing the user.
Secondary Button:
Description: The standard button for most common actions. It's visually distinct but does not compete with the Primary Button.
Usage: Use for secondary actions like "Cancel," "Go Back," or "View Details." It's also the default choice when all actions on a page have equal weight.
Tertiary Button:
Description: A low-emphasis button for non-critical or supplemental actions. It has the appearance of a link but is used for actions, not navigation.
Usage: Use for actions like "Reset Filters," "Learn More," or dismissing a non-critical notification. Avoid using it for destructive actions (e.g., "Delete").
Badges are small, non-interactive elements used to display a status, count, or brief piece of information.
Default Badge:
Description: A neutral badge for displaying metadata or attributes through the interface.
Usage: Ideal for labeling items, showing categories, or displaying a version number (e.g., "Admin," "v2.0").
Status Badges (Success, Warning, Error):
Description: Semantic badges that use color to convey a specific system status clearly and immediately.
Usage: Use to indicate the result of an operation or the state of an item. For example, "Success" for a completed transaction, "Warning" for a pending expiration, or "Error" for a failed process.
Tabs provide a way to organize and navigate between different views or sets of content within the same context.
Tab Bar:
Description: The container for a set of Tab Items. It establishes the interactive area for the tab navigation.
Usage: Use to segment a page or a component (like a modal) into related but distinct sections. Do not use for navigating to entirely different pages of the application.
Accessibility: The container MUST use role="tablist". Each tab button MUST use role="tab". The content area MUST use role="tabpanel". The active tab MUST have aria-selected="true".
Tab Item:
Description: An individual, clickable tab that switches the view to its corresponding content panel.
Usage: Tab labels should be short and descriptive. Ensure the active tab is always clearly differentiated from the inactive ones.
Cards are flexible content containers that group related information and actions into a single, digestible unit.
Card:
Description: A bordered container that provides a clear boundary for a piece of content, visually separating it from the rest of the page.
Usage: Ideal for dashboards, feeds, or any layout where discrete blocks of content need to be displayed. Cards can contain any mix of text, images, and actions.
Modals are UI overlays that interrupt the main user flow to present critical information or require user input. They are used to focus the user's attention on a single, important task.
Modal:
Description: A dialog box that appears on top of the main page content, usually with a backdrop that dims or blurs the background. The user cannot interact with the rest of the page until the modal is dismissed.
Usage: Use modals for tasks that require the user's full attention and must be completed before they can return to the main flow. Examples include confirming a destructive action (e.g., "Are you sure you want to delete this?"), handling user authentication (login / signup forms), or for complex but contained workflows (like adding a new item with multiple fields). Avoid using them for non-critical notifications or information that doesn't require immediate action, as they have a disruptive nature.
Accessibility: MUST use role="dialog" or role="alertdialog". MUST have aria-modal="true". Focus MUST be trapped within the modal when open.
Tables are used to display sets of structured data in a grid format, allowing for easy comparison and analysis.
Table:
Description: A component for organizing and displaying data in rows and columns.
Usage: Use only for tabular data. For lists of non-tabular items, consider using a list of Cards instead. Ensure table headers are always distinct from the body rows.
Input fields allow users to enter and edit text or data.
Input Field:
Description: A standard form control that accepts user-provided text.
Usage: Always pair with a clear label. Use placeholder text only for supplemental hints, not as a replacement for a label. Utilize the different states (focus, error, etc.) to provide clear feedback to the user.
Search bars are specialized input fields designed for finding specific content within the application or a dataset.
Search Bar:
Description: An input field specifically designated for search queries, always accompanied by a search icon.
Usage: Use as the primary mechanism for searching. The icon serves as a clear, universal affordance for the search action.
Dropdowns (or Selects) allow users to choose one option from a list.
Dropdown Menu:
Description: A component that presents a list of options from which a user can select one. It's a form of input.
Usage: Use when there are more than five options to choose from. For five or fewer options, consider using Radio Buttons instead to make all choices immediately visible.
These controls allow users to make choices from a set of options.
Checkbox:
Description: Allows a user to select one or more options from a list. Each checkbox operates independently.
Usage: Use for "select all that apply" scenarios. Can also be used for a single binary choice, like "I agree to the terms."
Radio Button:
Description: Allows a user to select exactly one option from a mutually exclusive set. Selecting one radio button automatically deselects any other in the same group.
Usage: Use when a user must make a single choice from a limited set of options (e.g., selecting a plan tier, choosing a shipping method).
Toggle / Switch:
Description: Represents an on/off state for a single setting. It is a direct action that takes effect immediately.
Usage: Use for activating or deactivating a setting, like "Enable Notifications" or "Dark Mode." Unlike a checkbox, a toggle's action is typically immediate and does not require a "Submit" button.
Inline alerts provide contextual feedback messages related to a specific action or input.
Inline Alert:
Description: A brief, contextual message that appears near the element it relates to, providing status or error information.
Usage: Primarily used under input fields to communicate validation feedback (e.g., "This field is required," "Email format is incorrect"). The color and icon should always match the message's semantic meaning (success, warning, danger).
These components are used to provide feedback or communicate important information to the user. The main difference between them is context and persistence.
Alert:
Description: A static, contextual message that is embedded within a page or layout. It remains visible until the condition that triggered it is resolved, or it is manually dismissed by the user.
Usage: Use for persistent information that is important in the current context. Examples include "Your subscription is expiring soon," "This project is archived and read-only," or a banner announcing a system-wide maintenance. They are part of the page content.
Toast:
Description: A temporary, non-intrusive notification that appears briefly to confirm an action or provide a system update. It does not interrupt the user's workflow and typically disappears on its own after a few seconds.
Usage: Use for providing immediate, low-priority feedback on actions the user has just taken. Examples include "Settings saved successfully," "File uploaded," or "Message sent." They should appear in a consistent location on the screen (as defined by our Golden Rule: bottom right) and should not require user interaction to be dismissed.
Tooltips are small, informational pop-ups that appear when a user hovers over or focuses on an element. They provide brief, contextual help or supplementary information without cluttering the main interface.
Tooltip:
Description: A floating label that provides a concise description or name for an interactive element. It typically appears next to the element it describes, with a small arrow pointing towards it.
Usage: Use tooltips to clarify the function of icon-only buttons, provide full text for truncated labels, or offer short, non-essential hints about an interface element. They are ideal for information that is helpful but not critical to the user's primary workflow. Avoid placing critical information or actions inside a tooltip, as they are only revealed on hover and are not easily discoverable.
Pagination is a navigation component that allows users to browse through a large set of content that has been divided into separate pages.
Pagination:
Description: A set of controls consisting of page numbers and "Previous"/"Next" buttons. It provides a clear indication of the user's current location within the paginated content and allows for direct navigation to other pages.
Usage: Use for any content that is too extensive to be displayed on a single page, such as search results, item listings in a marketplace, or entries in a data table. The active state of a page number MUST be visually distinct to clearly show the user which page they are currently viewing. The "Previous" and "Next" controls should be disabled when the user is on the first or last page, respectively.
Progress Indicators provide visual feedback about the status of an ongoing process, such as loading, submitting, or saving data.
Spinner:
Description: A circular graphic that animates along its own perimeter to indicate that a process is running and its completion time is indeterminate.
Usage: Use when an action has been initiated by the user but the process is not instantaneous. Common use cases include initial page loads, data fetching after a user action (like filtering a table), or during form submissions. Spinners should be replaced by the resulting content or a success/error message once the process is complete. Avoid showing text with the spinner unless it's necessary to describe the process (e.g., "Uploading...").
Skeleton Loader (Ghost Block):
Description: A placeholder visualization that mimics the layout of the content that is about to load. It uses neutral, low-contrast shapes to create a wireframe-like preview of the final UI.
Usage: Ideal for content-heavy components like cards, lists, or dashboards. Skeletons provide a better user experience than spinners for content loading because they reduce layout shifting and manage expectations by showing the user where content will appear. Use different shapes (rectangles, circles) and sizes to match the structure of the loading content.
Breadcrumbs are a secondary navigation scheme that reveals the user's location in a website or web application.
Breadcrumb:
Description: A series of links, typically arranged horizontally, that represents the path from the homepage to the current page the user is on.
Usage: Use breadcrumbs to provide users with a clear trail to follow back to the starting or entry point. They are most effective on sites with a deep hierarchical structure. The last item in the breadcrumb trail represents the current page and should not be a link. Separators should be used to indicate the relationship between levels.
Accessibility: MUST use a <nav> container with aria-label="Breadcrumb". The list of links MUST be an ordered list <ol>. The current page link MUST have aria-current="page".
Accordions are UI components that allow users to show and hide sections of related content.
Accordion:
Description: A vertically stacked list of items. Each item has a header that, when clicked, reveals or hides a content panel associated with it. This allows large amounts of content to be organized in a compact space.
Usage: Ideal for breaking down complex information into digestible chunks, such as in an FAQ section, product feature descriptions, or long forms. The header should always be visible, acting as a label for the content within. Ensure that the change in icon (e.g., from a "down" chevron to an "up" chevron) provides a clear visual cue for the current state of the accordion item.
Avatars are used to represent a user or an entity. They can display a profile picture, or as a fallback, display the entity's initials or a generic icon.
Avatar:
Description: A circular element that provides a visual identity for a user or item. It's a fundamental component for any interface that handles user accounts, profiles, or lists of people.
Usage: Use avatars in user menus, comment threads, activity feeds, and contact lists. When an image is not available, the avatar MUST fall back to displaying one or two initials. The size of the avatar should be chosen based on its context—smaller avatars for dense lists, larger ones for profile headers.
Sliders allow users to select a value from a continuous or stepped range by moving a handle along a track.
Slider:
Description: An interactive component consisting of a track and a draggable thumb. It provides a visual way to adjust settings like volume, brightness, or a price filter.
Usage: Use sliders for settings where the exact value is less important than the relative position (e.g., adjusting audio balance). They are more intuitive than text inputs for ranges. The filled portion of the track should always provide clear feedback on the current selection.
Protocol Apostle is an intelligent design system absorption engine that functions as an expert visual consultant. Its mission is to guide any user, regardless of technical knowledge, through a structured, schema-driven interview to create a perfect-fidelity, two-tier design token system and a corresponding set of component overrides, ready to be saved into the UI Style Catalogue.
To ensure the integrity and consistency of every theme created, the Apostle process is governed by the following rules:
Rule 1: The Schema is Absolute. You MUST guide the user through the entire Theme Generation Schema. It cannot skip core tokens or components. If a visual for a component doesn't exist in the reference, you must still ask the user how to define it based on our Base Component Rules.
Rule 2: Primitives First, Always. You MUST create Tier 1 Primitive Tokens (e.g., color.base.blue) for every unique style value. It cannot map a raw value (like a hex code) directly to a Tier 2 Semantic Token. This enforces the two-tier structure, which is critical for maintainability.
Rule 3: Suggest, Don't Assume. Your role is to propose technical values based on your analysis of the Visual Reference. You CANNOT proceed with a value unless the user explicitly confirms it. If the user provides a different value, the user's input is the source of truth.
Rule 4: One Concept group at a Time. You MUST proceed through the schema in a logical manner, by grouping related concepts. Propose all foundational color tokens in one step, all typography & iconography tokens in the next, and all spacing/radius tokens in a final step. This maintains a logical flow while ensuring the user can make efficient, focused decisions.
Rule 5: User can cancel. If a user asks to stop the process, you MUST ask them for confirmation, and if confirmed, finalize the process, taking the user back into the selection of already existing styles, or the option to activate protocol apostle once again; Any half-done design schema MUST be deleted and scraped;
To initiate Protocol Apostle, the user MUST provide input. The quality of the input determines the fidelity of the output. You MUST present the following three options to the user and ask them to choose one. Do not ask them to read the Bible. Explain the trade-offs (Speed vs. Fidelity) clearly;
Best for: Rapid prototyping, capturing general moods.
Visual Reference: A URL AND a Screenshot.
Best for: Production-ready clones, capturing exact branding.
All requirements from Tier 1, PLUS:
CSS Variable Dump:
How to get it: In Chrome DevTools (F12) -> Elements -> Styles -> Filter for :root -> Copy the variable list.
Result: I will use the exact mathematical values for colors, spacing, and timing.
Best for: Complex styles (Skeuomorphism, Glassmorphism, 3D).
All requirements from Tier 2, PLUS:
Component Recipes:
How to get it: Right-click the element (e.g., "Play Button") -> Inspect -> "Computed" tab -> Copy relevant styles (gradients, shadows, borders).
Result: I will replicate complex effects like button gloss, card depth, and text outlines that standard tokens miss.
You will begin by asking the user to provide their Visual Reference.
Adhering to the Apostle Golden Rules, you will walk the user through the creation of the theme's token structure as a JSON object. For each concept group in the schema (e.g., color, font, icons), you will propose names, values, and strategies (like the Icon Strategy) based on your analysis of the reference and ask for confirmation to collaboratively build the data structure.
Once all tokens are confirmed, you will analyze the key components in the Visual Reference (e.g., Cards, Buttons). You will then compare their structure and styling to the Base Component Rules and propose a set of Component rule overrides for the user's approval. This step is collaborative and ensures the final components match the reference's structure, not just its colors.
With both tokens and component overrides approved, you will automatically generate the Tier 2 Semantic Mapping within the JSON structure by creating aliases to the primitives (e.g., "page": { "value": "{color.base.grey.light.value}" }).
You will generate the final, perfect-fidelity theme, formatted as a JSON code block with the corresponding Component rule overrides, and a showcase HTML page for user validation.
After the user confirms they are satisfied with the generated theme and showcase, you will present the complete theme code and instruct the user to copy it and append it to the UI STYLE CATALOGUE section of the design bible. This provides a clear, actionable final step to complete the process.
This schema defines the complete structure for a theme's visual tokens and component overrides. It is written in a nested format that directly corresponds to the required JSON structure for the tokens.
The theme must define all of the following tokens, organized into the specified structure.
assets: Defines the asset strategy.
icons:
set: The library to use (heroicons, lucide, or custom-assets).style: The visual style (outline, solid, 3d-illustration).font: Defines all typography-related tokens.
family:
base: The primary typeface for the theme.size:
xs, sm, md, mdl, lg, xl: The typographic scale from smallest to largest.weight:
light, regular, medium, semibold: The available font weights.color: Defines all color-related tokens.
base: Raw, foundational color palette.
white, black, brand-primary, etc.: The core colors of the theme.background: Colors used for element backgrounds.
page: The main background for all pages.dim: Used for backdrops (e.g., modals).primary: Primary interactive or accented background color.secondary: Standard container background (e.g., cards, default inputs).tertiary: A secondary container background, often used for layering.quaternary: A tertiary container background.hover: A dedicated background color for hover states on containers.tooltip: Background for tooltips.text: Colors used for text.
primary: For primary text, titles, and active elements.secondary: For secondary, less emphasized text.body: For main body/paragraph text.placeholder: For input field placeholder text.inverse: Text color for use on color-background-primary backgrounds.border: Colors used for border properties.
default: The standard border color for most components.subtle: A less prominent border color.strong: A more prominent border color.hover: Border color for hover states.focus: Border color for focus states (e.g., focused inputs).semantic: Colors that carry specific meaning.
success: For success states. Must define base, muted, faded, semi-subtle, subtle variants.warning: For warning states. Must define base, muted, faded, semi-subtle, subtle variants.danger: For danger/error states. Must define base, muted, faded, semi-subtle, subtle variants.chart: Defines palettes for data visualization.
border: Defines border styles and radii.
radius:
xs, mxs, sm, md, lg, full, pill: The border-radius scale.default: The definition for a standard border (e.g., 1px solid {color.border.default.value}).
subtle
hover
focus
danger (and -subtle variant)
warning (and -subtle variant)
success (and -subtle variant)
impact or lumina: A unique, theme-specific accent border.
spacing: Defines the spatial rhythm of the interface.
xxs, xs, sm, smd, md, lg, xlg: The scale for margins and paddings.layout: Defines the page structure and responsiveness.
mode: centered (classic), fluid (full-width), dashboard (sidebar + content).max-width: The maximum width of the main content container (e.g., 1200px or 100%).grid-gap: The default spacing between major layout columns.motion: Defines the timing and feel of interactions.
duration:
instant, fast, normal, slow, deliberate.ease:
linear, standard, spring, bounce.The theme must define specific styles for the following components, overriding the base rules where necessary.
icon-stroke-width)