Use this capability whenever you write, review, or refactor the styles of a React component — a CSS Module, a Unistyles stylesheet, a theme file, or the global styles beneath them. It owns implementation mechanics: which properties belong to a component and which belong to its consumer, what shape the design tokens take and how they are consumed, how a surface adapts to viewport, container, pointer type, colour gamut and motion preference, and in what order the properties are written.
It does not own design rationale. Visual hierarchy, contrast targets, what a colour means, how much motion is tasteful, whether a state reads as interactive — those belong to a high-fidelity UI design capability. Where a rule here has a design counterpart, this skill states the mechanic and points at that capability rather than restating its reasoning.
This skill is self-contained and prescribes token shapes, never token values. The palette, the ramp, the type scale, and the spacing steps are the host project's; bind every value to the project's semantic tokens, and where a needed role is missing, add the token rather than inlining a literal.
Platform adapters. Two references are conditional, not universal:
- Apply the CSS Modules rules to a pre-existing component that already uses CSS Modules, and to a new component only when CSS Modules is the project's primary styling mechanism.
- Apply the Unistyles rules to a pre-existing component that already uses Unistyles, and to a new component only when Unistyles is the project's primary styling mechanism. Unistyles guidance here is scoped to mobile native.
Everything outside those two references is platform-neutral and applies either way.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Style Composition
See style-composition.md for:
- separating contextual consumer placement from intrinsic defaults, internal coordinates, structural/state paint order, overlay-host geometry and neutral root resets
- accepting and merging an incoming
classNameorstyle, binding-preserving Unistyles arrays, and effective consumer control when internal animation conflicts - deciding when a consumer overrides a child's styles rather than the child growing a prop
- pairing one style module per component, and sharing a component instead of sharing a stylesheet
- sizing a child from its parent, and the "appearance here, size there" split
Design Tokens and Theming
See theming.md for:
- adding or renaming a token, the token families a project declares, and the shape of each
- composite named text roles, and why family, size, leading, and weight travel together
- px-keyed spacing steps, named radius and border-width tiers, and a platform-defined native hairline constant rather than a stylesheet-creation API
- duration and role-named easing tokens
- writing a literal colour, spacing, radius, border-width, type, duration, or easing value, snapping it to the nearest step, and the closed list of literals that stay legal
- reading a token outside a stylesheet — icon colour and size, navigator options, animated values
Colour and Gamut
See color-and-gamut.md for:
- the 13-step ramp as an internal primitive tier, and the semantic role names components actually consume
- the step-to-role table, the colour schemes a project declares, and the alpha ramp
- picking a step by role rather than by how it looks in one scheme, and what a per-scheme override signals
- preferring a wide-gamut colour format, deciding whether it needs an sRGB fallback from the project's support matrix rather than from the format, and which of
@supportsand@media (color-gamut:)answers which question - the colour-space reality on mobile native, and what it means for parity with web
Fluid and Responsive Sizing
See fluid-and-responsive.md for:
- fluid scalar tokens built with
clamp(), and which tokens stay fixed - choosing between viewport units and container units, and why root-level tokens force the viewport
- tiering a surface against its own container rather than the viewport, and propagating the tier to descendants
- declaring breakpoints, and what belongs at a breakpoint versus in proportional sizing
- measuring a parent on mobile native and feeding the measurement into a style
Adaptive Styling
See adaptive-styling.md for:
- which conditions belong in a media query and which belong elsewhere
- honouring a reduced-motion preference on both platforms
- gating hover styles on the primary pointer, and why that gate differs from the one used for sizing
- sizing an interactive target from the pointer type, on both axes, and expanding a hit area without moving the visual
- print styles, and writing direction-agnostic styles for right-to-left layouts
Feature Support and Fallbacks
See feature-support.md for:
- authoring, keeping, or removing a fallback for a web platform feature
- deciding a guard from the feature's interoperability across the project's own browser support matrix, rather than from its format or its age
- the reachability test that separates a live fallback from dead code, and the outward direction it runs in
- a block-gating feature such as
@scopeas a one-time adoption decision rather than a per-use guard @supportsfor what the browser understands against@mediafor what the environment has- interoperability and consequence as the two axes a guard answers separately
Style Property Order
See style-property-order.md for:
- writing or reviewing the property group order inside a single style block
- where custom properties, nested at-rules, and pseudo-selector blocks sit
- writing or reviewing composed-style order — base, variant, state, animated, consumer — without mistaking array order for Reanimated precedence
Global Styles
See global-styles.md for:
- adding a rule to a global stylesheet, and what belongs in global styles versus a component
- weakening global styles so a component can override them without a specificity fight
- declaring or reordering cascade layers on web
- setting the colour-scheme declaration, scrollbar, and selection styling
- the mobile-native equivalents of a global stylesheet
CSS Modules (web)
See css-modules.md for:
- creating a
.module.cssfile with the module skeleton — cascade layer, scope, and the zero-specificity scope root - keyframes placement and animation naming
- propagating style context to descendants through custom properties
- size-based styling with container queries and container-relative units
- styling a third-party component through its state attributes, and the one narrow case for
!important - scroll-driven animation, modern units, and logical properties
Unistyles (mobile native)
See unistyles.md for:
- writing a Unistyles
StyleSheet.createcall versus a narrowly justified React Native constants-only token read - configuring native System adaptation versus explicit Light/Dark selection, mutually exclusive adaptive/initial settings, and product-owned fallback policy
- safe-area-aware styling with the mini runtime
- choosing between variants and dynamic functions
- parent-size-aware styling from a measured layout
- reading the theme outside a stylesheet
- platform-forked style files, and the navigation-cloning caveat that silently drops styles
Verifying a Styling Change
A styling change is verified by looking at the surface under every condition the rules above make conditional — not by the type-checker, which sees none of them. Reviewing one rendering proves one branch. This section names the checks a styling change earns; how the result is then reported — which of them ran, which were skipped, and what risk a skip leaves — belongs to a software development capability under its verification topic, which owns it for every kind of change.
Guidelines:
- MUST check both colour schemes for any change that touches colour; a surface legible in one and not the other is a defect, not a polish item.
- MUST check both pointer classes for any change to an interactive surface — a coarse-pointer rendering for target size, a fine-pointer rendering for hover.
- MUST check the reduced-motion branch whenever an animation or transition is added or changed.
- MUST check the width range a fluid or container-tiered surface spans, at minimum the two ends and one point either side of each breakpoint.
- SHOULD check a wide-gamut display and an sRGB display when a colour is authored outside the sRGB gamut.
- SHOULD check a right-to-left rendering when a change adds directional properties.