Instruction file imported from Ocean-Industries-Concept-Lab/openbridge-webcomponents (.cursor/rules/css-postcss.mdc). Copyright stays with the author.

CSS / PostCSS Reference

Full reference with diagrams, code examples, and complete mixin inventories lives in IMPLEMENTATION_GUIDELINES.md § PostCSS. This file summarises the key concepts so agents have immediate context.

Key concepts

• variables.css is generated by the obc-figma-plugin (Figma community plugin 1448419213272098259) — do not hand-edit. Token additions, renames, or value changes happen in Figma (or in the plugin's rename() function), then the whole file is replaced with the plugin's cssvariables codegen output; the procedure and what to strip from the output are in figma-refresh.md.
• Global palette: src/palettes/variables.css — four themes (day, dusk, night, bright) via data-obc-theme attribute on :root.
• Two-layer color model: Raw primitives (--base-blue-*, --base-gray-*, --base-cyan-*, …, plus -tint variants) are redefined per theme. Semantic tokens (e.g. --instrument-enhanced-primary-color, --element-active-color, --automation-medium-base-blue-*) are layered on top and consumed by components. Semantic tokens are stored as literal rgb(...) values per theme — not as var(--base-…) references — so overriding only the primitives is not enough to fully repaint the UI; override both layers (or only the semantic tokens) when re-skinning. The night theme already uses a teal/green (rgb(88, 200, 162)) for --instrument-enhanced-primary-color, proving the architecture supports non-blue accents. A few hot spots reference raw primitives directly: charthelpers/constants.ts (CHART_SECTOR_ENHANCED_COLORS, used by line/area/donut/pie charts), ar/building-blocks/poi-line/*.css, and the --automation-medium-base-blue-* tokens. Consumers can re-theme without forking by shipping a stylesheet after variables.css that redeclares the relevant tokens under each :root[data-obc-theme="…"] selector; Chart.js components read CSS vars at render-time via getCssVariableValue(), so overrides must be present on an ancestor before the chart mounts.
• Touch target / Visual target: Interactive components use a two-layer DOM — an outer invisible touch target (default 48 px) and an inner visible wrapper (default 32 px). The @mixin style bridges them via the visibleWrapperClass parameter.
• @mixin style: PostCSS build-time mixin generating six interaction states (enabled, activated, hover, pressed, focus-visible, disabled). Parameters: style=<flat|normal|raised|amplified|indent|selected>, optional visibleWrapperClass=.class, optional noClick flag for display-only sub-parts.
• Color token convention: Surface colors follow --{variant}-{state}-background-color / --{variant}-{state}-border-color. Text/icon colors follow --on-{variant}-{role}-color (roles: active, neutral, disabled).
• Size variants: .obc-component-size-regular (default) / -medium / -large / -xl classes on an ancestor scale all --ui-components-* sizing tokens via CSS variable inheritance.
• Font mixins: Three families — UI (font-button, font-label, font-body, etc.), Instrument (font-instrument-value-*, font-instrument-label, etc.), Automation (font-automation-value-*). Full list in IMPLEMENTATION_GUIDELINES.md.
• Alert mixins: alert-alarm, alert-critical, alert-caution in src/mixins/alert.css. Flashing drives the CSS @property registered --flash-fast-on/off, --flash-slow-on/off and --flash-very-slow-on/off (src/palettes/manual.css), but is driven from TypeScript via the Web Animations API in src/palettes/blinking.ts (installFlashing()), not by a CSS @keyframes — FlashingController in alert-frame, alert-icon and alert-button-item installs it. Components bind opacity or widths to those custom properties; the tempo table lives in blinking.ts (see ui-components.md § Alert flashing).
• --obc-can-hover: CSS variable kill-switch for hover feedback (defined in src/main.css, consumed by @mixin style via color-mix()).
• Icon slots: use <obi-placeholder></obi-placeholder> or other <obi-*> icons (1000+ available).

Comments

One short line per non-obvious declaration — see coding-standards.md § CSS.