// CSS Modules conventions, Stylelint rules, design tokens (spacing, colors, typography, border-radius), and patterns for the Opentrons monorepo. Use when working with .module.css files or styling React components in app/, components/, protocol-visualization/, protocol-designer/, or other JS packages.
Conventions for the analyses snapshot testing framework in analyses-snapshot-testing/. Use when working with protocol analysis snapshots, adding protocols, updating snapshots, or running snapshot tests.
Vite demo and Playwright + Applitools tests for packed @opentrons JS packages in js-package-testing/. Covers components, shared-data, step-generation, and protocol-visualization. Use for integration testing, package linking, or visual testing.
TypeScript conventions, React patterns, testing, styling, and import rules for the Opentrons monorepo JS/TS packages. Use when working with TypeScript or React files in app/, components/, shared-data/, step-generation/, protocol-designer/, protocol-visualization/, opentrons-ai-client/, or other JS/TS packages.
Protocol Designer (PD) application architecture, Redux slices, step/timeline system, domain concepts, and dev workflow. Use when working with files in protocol-designer/ or discussing PD features, steps, timelines, or protocol design.
Component creation checklist and ai-client-specific patterns for React .tsx files in opentrons-ai-client/ and protocol-designer/. Use when creating new React components in these packages.
Conventions for the opentrons-ai-client React/TypeScript frontend — project structure, API integration, state management (Jotai), feature flags, types, and testing. Use when working with files in opentrons-ai-client/ or discussing the AI client application.
| name | css-modules |
| description | CSS Modules conventions, Stylelint rules, design tokens (spacing, colors, typography, border-radius), and patterns for the Opentrons monorepo. Use when working with .module.css files or styling React components in app/, components/, protocol-visualization/, protocol-designer/, or other JS packages. |
File names are lowercase, no separators, suffixed with .module.css, and match the component name:
ComponentName/
├── index.tsx
├── componentname.module.css
└── **tests**/
└── ComponentName.test.tsx
Examples: navbar.module.css, labwarebutton.module.css, textareafield.module.css
Stylelint enforces the pattern /^[a-z0-9_]+$/ — snake_case only (lowercase letters, digits, underscores).
Use a component_element or element_modifier structure:
/* Base classes */
.button {
}
.slider_container {
}
.crumb_link {
}
/* State/modifier variants */
.button_active {
}
.textarea_error {
}
.title_text_center {
}
.crumb_link_inactive {
}
import styles from './componentname.module.css'
export function MyComponent(): JSX.Element {
return <div className={styles.wrapper}>content</div>
}
clsxUse clsx for combining or conditionally applying classes:
import clsx from 'clsx'
import styles from './componentname.module.css'
export function MyButton({ isActive, isError }: Props): JSX.Element {
const className = clsx(styles.button, {
[styles.button_active]: isActive,
[styles.button_error]: isError,
})
return <button className={className}>Click</button>
}
All tokens are defined in components/src/styles/global.css. Always use these variables instead of hard-coding values for colors, spacing, typography, and border-radius.
| Variable | Value |
|---|---|
--spacing-2 | 0.125rem (2px) |
--spacing-4 | 0.25rem (4px) |
--spacing-6 | 0.375rem (6px) |
--spacing-8 | 0.5rem (8px) |
--spacing-10 | 0.625rem (10px) |
--spacing-12 | 0.75rem (12px) |
--spacing-16 | 1rem (16px) |
--spacing-20 | 1.25rem (20px) |
--spacing-24 | 1.5rem (24px) |
--spacing-32 | 2rem (32px) |
--spacing-40 | 2.5rem (40px) |
--spacing-44 | 2.75rem (44px) |
--spacing-48 | 3rem (48px) |
--spacing-60 | 3.75rem (60px) |
--spacing-68 | 4.25rem (68px) |
--spacing-80 | 5rem (80px) |
--spacing-120 | 7.5rem (120px) |
Core: --white (#fff), --black-90 (#16212d), --black-80 (#24313f), --black-70 (#39495b)
Grey: --grey-10 through --grey-60 (10, 20, 30, 35, 40, 50, 55, 60)
Blue: --blue-10 through --blue-60 (10, 20, 30, 35, 40, 50, 55, 60)
Purple: --purple-20 through --purple-60 (20, 30, 35, 40, 50, 55, 60)
Green: --green-20 through --green-60 (20, 30, 35, 40, 50, 60)
Red: --red-20 through --red-60 (20, 30, 35, 40, 50, 55, 60)
Yellow: --yellow-20 through --yellow-60 (20, 30, 35, 40, 50, 60)
Flex brand: --flex-40, --flex-50, --flex-55
Semi-transparent: --transparent-white-80, --transparent-white-50, --transparent-black-10, --transparent-black-60, --transparent-black-80, --transparent
Some colors (green, purple) have touchscreen variants that activate when
components/src/styles/global.cssapplies the.enable_touchscreen_colorsclass. The default values are non-touchscreen.
--border-radius-2, --border-radius-4, --border-radius-8, --border-radius-12, --border-radius-16, --border-radius-40, --border-radius-full (pill/circle)
Font size: --font-size-caption (10px), --font-size-label (11px), --font-size-p (13px), --font-size-h4 (13px), --font-size-h3 (14px), --font-size-h2 (15px), --font-size-h1 (19px), --font-size-20, --font-size-22, --font-size-28, --font-size-32, --font-size-38, --font-size-80
Font weight: --font-weight-light (300), --font-weight-regular (400), --font-weight-semi-bold (600), --font-weight-bold (700)
Line height: --line-height-12, --line-height-16, --line-height-18, --line-height-20, --line-height-24, --line-height-28, --line-height-36, --line-height-42, --line-height-48, --line-height-96
| Property | Use token? | Example |
|---|---|---|
color, background-color, border-color | Yes | var(--blue-50) |
padding, margin, gap | Yes | var(--spacing-16) |
border-radius | Yes | var(--border-radius-8) |
font-size | Yes | var(--font-size-p) |
font-weight | Yes | var(--font-weight-semi-bold) |
line-height | Yes | var(--line-height-20) |
width, height, max-width, min-height | No — use explicit rem | 15rem, 100vh |
box-shadow | No — use px | 0 0 0 2px var(--blue-50) |
240px / 16 = 15rem)box-shadow values and <img> tag dimensionspadding over margin for wrapper and container elementscalc() expressions.button:focus {
outline: none;
box-shadow: 0 0 0 2px var(--blue-50);
}
.button:hover:not(:disabled) {
background-color: var(--grey-10);
}
.button:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.input:focus {
border-color: var(--blue-50);
}
Always guard hover styles with :not(:disabled) on interactive elements.
Stylelint allows the composes property for class composition:
.base_button {
padding: var(--spacing-8) var(--spacing-16);
border-radius: var(--border-radius-4);
}
.primary_button {
composes: base_button;
background-color: var(--blue-50);
color: var(--white);
}
Use :global() to target non-module classes (e.g., from React Router or third-party libraries):
.nav_link:global(.active) {
color: var(--blue-50);
}
The repo uses stylelint-config-standard + stylelint-config-idiomatic-order (property ordering). Key enforced rules:
/^[a-z0-9_]+$/width, height, flex)@value at-rule is still allowed but deprecated — avoid in new code# Lint all CSS
make lint-css
# Auto-fix all CSS
make format-css
# Lint a single file
pnpm stylelint path/to/componentname.module.css
# Auto-fix a single file
pnpm stylelint path/to/componentname.module.css --fix
Always run make lint-css and fix any issues before committing.
components/src/styles/borders.module.css — old border tokens (--bd-radius-*, --bd-width-*, --shadow-lvl-*). Use global.css tokens instead.components/src/styles/typography.module.css — old typography tokens (--fs-*, --fw-*, --lh-*). Use global.css tokens instead.styled-components — the codebase is migrating away. Always use CSS Modules for new styles.@value declarations — still parsed by stylelint but deprecated. Use CSS custom properties.