theme-system
Enforces the use of semantic theme tokens for all UI styling and component development.
Install
mkdir -p .claude/skills/theme-system && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/7480" && unzip -o skill.zip -d .claude/skills/theme-system && rm skill.zipInstalls to .claude/skills/theme-system
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when creating or modifying OpenChamber UI components, styling, colors, buttons, visual states, themes, or icons.Key capabilities
- →Apply semantic theme tokens
- →Implement standardized button variants
- →Manage sprite-based iconography
- →Apply status and interactive states
How it works
It enforces a strict design system where UI components must consume predefined semantic tokens instead of raw values. It mandates the use of specific shared primitives for buttons and icons.
Inputs & outputs
When to use theme-system
- →Style UI components using theme tokens
- →Add new interface icons via system sprites
- →Implement standardized button variants
- →Apply status colors for user feedback
About this skill
Theme System
Core Rules
- Use semantic OpenChamber theme tokens; never hardcode hex colors or generic Tailwind palette colors.
- Use shared UI primitives before introducing feature-local controls.
- Every dropdown-style value-picker trigger takes its chrome from
dropdownTriggerVariantsinpackages/ui/src/components/ui/dropdown-trigger.ts; call sites add layout classes only. Deliberately chrome-less pickers in composers or headers are the exception. - Apply hover tokens only to interactive elements.
- Use status colors only for actual status/feedback.
- Use selection tokens for selected state and primary tokens for primary actions.
Load References By Task
| Task | Required reference |
|---|---|
| Choosing colors/tokens or reviewing styled examples | references/tokens-and-examples.md |
| Adding, converting, storing, or generating icons | references/icons.md |
| Adding built-in or custom themes | references/adding-themes.md |
Load every matching reference before editing. How a screen should look and behave (depth and borders, which surface class to use, layout stability, sizing, composition, text density) is owned by openchamber-ui-guidance; load it for any visible UI change. User-facing or accessible text must load locale-ui-patterns. Spacing, positioning and directional icons follow rtl-layout, which owns how a layout works in both directions.
Token Decision
- Code display ->
syntax.* - Error/warning/success/info ->
status.* - Primary CTA ->
primary.* - Hover/pressed/focus ->
interactive.* - Selected/active state ->
interactive.selection* - Background/text/border layer ->
surface.*and semantic utility classes
Prefer CSS variables/classes for component styling. Use useThemeSystem() only when an API requires resolved color values.
Button Contract
Use Button from packages/ui/src/components/ui/button.tsx; do not create wrappers such as ButtonSmall or ButtonLarge.
| Variant | Use |
|---|---|
default | Primary local action |
outline | Visible secondary action |
secondary | Soft secondary action |
ghost | Quiet row/toolbar action |
destructive | Destructive action |
chip | Compact selectable option with aria-pressed |
link | Rare inline text action |
| Size | Use |
|---|---|
xs | Dense row/list control |
sm | Compact action |
default | Standard action |
lg | Prominent action |
icon | Icon-only square action |
Do not hardcode button height/padding when a size variant exists. Do not recreate selection/destructive styling with ad-hoc classes.
A button that opens a page, panel, or search field is a toggle: while what it opened is on screen it carries aria-pressed and the selection tokens, and the next click closes it. Closing a search field also clears its query, so the list never stays filtered by text nobody can see.
Every dropdown trigger on desktop is 28px (dropdownTriggerVariants() default, SelectTrigger), in forms and toolbars alike. Toolbars, filter rows and the context panel header use 28px throughout: Button size="sm", <Input inputSize="compact">, and the active-pill tab strip (its default). Form inputs and buttons stay 32px (default). Pick the size variant instead of overriding h-* at the call site to match a neighbour; mobile/touch branches keep their own larger sizes (mobile, touch).
Extensions draw these controls from their own copy, the SDK UI kit in packages/sdk/src/ui. A change to a shared primitive's size, radius, or states (button, input, dropdown trigger, select item, checkbox, tabs, badge) also changes its twin in packages/sdk/src/ui/style.ts in the same change: appearance in GUEST_UI_LOOK_CSS, which the server serves to installed extensions, sizes in UI_SIZE_CSS, which reach an extension when its author rebuilds. Then rebuild the SDK example bundles (packages/sdk/DOCUMENTATION.md).
Keyboard Navigation Contract
- Menus, selects, and autocomplete pickers with ArrowDown/ArrowUp navigation must also support Ctrl+N/Ctrl+P, including submenus and searchable lists.
- Keep this behavior in shared components so callers inherit it. Use the keyboard mapping in
packages/ui/src/components/ui/dropdown-navigation.ts; feature code must not duplicate key detection. - Lists that own their active option or stop keyboard propagation must call the shared navigation helper at their own event boundary. Wrapping a custom list in a dropdown does not guarantee that its navigation events reach the wrapper.
- Route both key pairs through the same selection logic, preserving disabled-item skipping, boundary or wrap behavior, highlight, and scroll visibility. Consume each navigation event once, only while the menu or picker is active; preserve IME text entry and other modifier chords.
- Verify Ctrl+N/P alongside arrow keys in the real component, including search-input focus, submenus, and closed state. A key-mapping unit test alone does not verify event propagation or focus behavior.
Icon Contract
import { Icon } from '@/components/icon/Icon';
<Icon name="check" className="size-4" />
Never import icons directly from @remixicon/react. Use IconName for icon values stored in arrays, objects, state, or config. Icon has no size prop. Run bun run icons:generate when introducing a sprite name, and never edit sprite.ts manually. Load references/icons.md for the complete workflow.
Animation Contract
Animate only transform and opacity. Use transform: rotate(...), not the individual rotate property. Non-composited properties recalculate style continuously; geometry also triggers layout. Animate only while conveying live information.
Motion that can stay on screen for minutes follows the state it shows:
- Steady state stands still: connected, failed, degraded, "Unavailable", the provider logo while the agent works, read-aloud playing (its icon turns
--primary-text). Show a static icon in the state's color. - A wait that can last spins on the shared clock: a running project action, worktree setup or removal, a space being made, CI checks, loading sessions or models, walkthrough generation, an OpenCode update. Render
Spinner(components/ui/spinner.tsx): eight bars, four steps a second. - A wait that cannot spin blinks: a status dot (6 px,
size-1.5), the recording dot, a loading skeleton. ApplyuseWaitingBlink(active); it dims every other second. The splash logo steps instead: its roof tiers light up one at a time, once a second, throughuseWaitingPhase. - Waiting text gets dots: "Thinking", "Waiting for approval". Put
BusyDots(components/ui/busy-dots.tsx) after the label; drop any "…" from the string. - A spinner that lasts seconds (a button after a click, a quick load, refresh) keeps
animate-spin. - Hidden stops. A surface kept mounted while hidden wraps its content in
PauseClock(components/ui/pause-clock.tsx); the context panel's zones already do. Aninertsubtree pauses its CSS animations (index.css).
Spinner, useWaitingBlink, BusyDots and live counters (useDurationTickerNow) share one clock (hooks/useDurationTicker.ts): a page draws four frames a second while a spinner shows and one otherwise, however many indicators are on screen. Each tick re-renders the component that calls the hook, so call it in the indicator itself. lib/infiniteAnimations.test.ts fails on any new infinite CSS animation outside the short ones it lists. The cost behind these rules is in performance-engineering, "Motion That Stays On Screen".
Springs are the app's easing. lib/motion/springs.ts turns a spring (perceived duration, bounce) into a CSS linear() easing and writes it to --oc-motion-<name>-duration / -easing: popup for menus, selects and tooltips (oc-popup-motion, which transitions only opacity and transform; never transition-all on a popup), layout for a control easing into a new width. Change a spring in MOTION_SPRINGS and paste its generated values into design-system.css (its test keeps them in step). In development Cmd+Alt+M opens live knobs for them. A control whose width follows its value (a picker) uses useWidthMorph(ref) (lib/motion/useSizeMorph.ts): it watches the content, retargets from where the control stands when a part arrives late, and clips the text while it moves. An open popup whose content changes uses useHeightMorph(ref) on its box the same way; DropdownMenuContent calls it for every menu. Its positioner (base-ui) or bottom-full keeps the anchored edge in place in every painted frame, so the hook never moves the popup itself. These are the accepted size animations: once per content change, on a small control or an open popup.
For any other technique, load performance-engineering and scripts/perf/DOCUMENTATION.md, measure it with bun run profile:animation, and add a fixture variant when needed. This skill owns animation styling; performance-engineering owns performance evidence.
Completion Criteria
- Animations are limited to
transformandopacity, or their cost was measured and accepted. - Nothing that can stay on screen for minutes runs an infinite CSS animation: steady states stand still, waits use
Spinner,useWaitingBlinkorBusyDots. - No hardcoded/palette colors were introduced.
- Buttons use shared variants and sizes.
- Menus and pickers satisfy the keyboard navigation contract without caller-specific key handling for standard shared components.
- Icons use
Icon/IconName, and generated sprite changes are intentional. - Hover, selection, primary, and status semantics are distinct.
- Light/dark/high-contrast and long-text states remain legible.
- Every applicable contract and loaded task reference was verified with relevant visual/runtime validation and generated-asset checks.
When not to use it
- →Hardcoding hex colors
- →Using generic Tailwind palette colors
- →Creating custom button wrappers
Limitations
- →No hardcoded hex or palette colors allowed
- →Must use shared Button and Icon primitives
How it compares
It replaces ad-hoc styling with a centralized token-based contract that prevents visual drift and hardcoded color values.
Compared to similar skills
theme-system side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| theme-system (this skill) | 1 | 4mo | No flags | Beginner |
| web-design-reviewer | 7 | 10mo | No flags | Intermediate |
| baseline-ui | 3 | 10mo | No flags | Intermediate |
| bencium-innovative-ux-designer | 1 | 8mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
web-design-reviewer
github
This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level.
baseline-ui
agentset-ai
Enforces an opinionated UI baseline to prevent AI-generated interface slop.
bencium-innovative-ux-designer
bencium
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
frontend-system
ZroZoom
UI/UX expert. Use for creating components, styling (Tailwind), accessibility, and translations (I18n). Trigger when: create a component, change appearance, add a chart, translate, stwórz komponent, zmień wygląd, dodaj wykres, przetłumacz.
ui-skills
Ktasl
Apply strict, opinionated UI constraints to any UI work (React/Tailwind) in this conversation.
userinterface-wiki
raphaelsalaja
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.