css-styling

CSS Editing Instructions

CRITICAL: Before Editing Any CSS File

REQUIRED STEP: Before making any changes to a .css file, you MUST read the corresponding .tsx file(s) that use it:

1. Look for .tsx files with the same base name (e.g., ComponentName.tsx for ComponentName.module.css)
2. Search for imports of the exact CSS filename, including side-effect imports.
3. Read ALL .tsx files that import the CSS file before proceeding with edits

You may also need to edit the matching .tsx file and its structure to properly edit CSS.

CSS Architecture

This project uses CSS Modules. Component CSS files should be named *.module.css and placed alongside their corresponding .tsx component files. App-level stylesheets in app/styles/ provide foundational styles such as resets and font registration; do not put component styles there.

Do not write inline css in the style attribute (unless there is a javascript value being attached).

Custom Fluent Components

Do not use CSS to recreate components that already exist in CoreAI or Fluent. Before editing components, invoke the react-components skill for proper component usage guidelines. Most appearance and interaction styles are already handled by documented CoreAI components and props. If an appropriate prop is available, use it instead of writing CSS.

CSS @layers

There are 3 named CSS @layers in this app, ordered base, griffel, and common, plus unlayered CSS (which is not a named layer). The base layer contains the foundational box-sizing reset in app/styles/globals.css. The griffel layer encapsulates Fluent's styles through the app-owned layered renderer - NEVER write CSS into the griffel layer. The common layer is for common components inside the app/components/common folder and app-level resets; all components in this folder should use this layer, and component styles outside it should not. All other component styles should be written outside of these layers.

General Guidelines

No Global CSS: Do not write global CSS selectors (e.g., body, h1) outside of a scoped CSS class for component styling. All component styles must be scoped using CSS Modules. App-level stylesheets in app/styles/ provide foundational resets, font registration, and app-wide variable defaults, not component styling. Use Nested Classes: Scope styles to specific elements within the component using nested class selectors. Avoid !important: Do not use !important in CSS rules. Instead, refactor the CSS or component structure to achieve the desired specificity.

Responsive Breakpoints — Container Queries

CRITICAL: Do NOT use @media (width ...) for responsive width breakpoints. Use @container app (width ...) instead.

This app uses CSS container queries so that responsive behavior responds to the actual available content width, not the viewport. Panels that reduce the content container's available width affect its breakpoints; the app-local floating feature selector is fixed-position and does not consume layout width.

The ContainerQueryProvider component (wrapping the app children with styles.fullscreenContainer in app/components/shell/AppContent.tsx) establishes container-type: inline-size with container-name: app.

Correct — Container Query

@container app (width <= 768px) {
  .sidebar {
    display: none;
  }
}

Wrong — Viewport Media Query

/* ❌ DO NOT use @media for width breakpoints */
@media (width <= 768px) {
  .sidebar {
    display: none;
  }
}

When to still use @media

• Height queries: @media (height <= 480px) — container queries only support inline-size
• User preferences: @media (prefers-color-scheme: dark), @media (prefers-reduced-motion: reduce)
• Accessibility: @media (forced-colors: active)
• Elements in portals/top-layer: Dialogs, popovers, and other portal-rendered elements that exist outside the container tree (these still need viewport @media queries)

Layout

CSS should primarily be used for layout, spacing, borders, and backgrounds. Avoid using CSS for text styles, component styles, or interaction styles. Most of these are handled by React components and props. Prefer using flexbox with gap for most layouts instead of block with margin. Grid is acceptable for more complex layouts.

Reduce nesting of HTML elements where possible - prefer a flatter structure.

Text Styling

Text Properties: Avoid writing these CSS properties directly in CSS files. The components handle most of these by default.

• font-size
• font-weight
• font-family
• line-height
• color (for text color)

EXCEPTION: Text properties inside @container queries for responsive typography (e.g., scaling a heading on mobile) should be kept in CSS — the Text component doesn't handle container-based sizing.

INSTEAD: Where these properties are applied to a Text, span, or other text element, refactor to use the documented Text component from @coreai-ds/react-components and replace any text CSS properties with preset and foreground props.

import { Text } from '@coreai-ds/react-components';

<Text preset="body" foreground={3}>
  Your text here
</Text>;

Text Component Presets & Foreground

Presets (size from smallest to largest):

• bodyXS (10px) / bodyXSStrong (10px semibold)
• bodyS (12px) / bodySStrong (12px semibold); heading6 is an alias of bodySStrong
• body (14px) / bodyStrong (14px semibold); heading5 is an alias of bodyStrong
• heading4 (16px semibold)
• heading3 (20px semibold)
• heading2 (28px semibold)
• heading1 (40px semibold)

Foreground (text color intensity):

• 1 - Headings
• 2 - Body text
• 3 - Subtle/muted/secondary
• 4 - Disabled/placeholder
• 'disabled' - Disabled text

Additional properties:

• block - makes the text a block element
• italic - makes the text italic
• font - sets the font family - base | monospace
• as - html element to render as (e.g., 'p', 'span', 'h1', etc.)

Don't use Fluent's fixed typography components (like <Body1> or <Title2>) directly. Always use CoreAI <Text> with preset and foreground props.

When you encounter these properties in existing CSS: Refactor the code to remove them from CSS and use the Text component in the .tsx file instead.

Combining CSS Classes

When applying multiple CSS classes, use the clsx utility:

import clsx from 'clsx';
import styles from './Component.module.css';

<div
  className={clsx(
    styles.class1,
    condition && styles.class2,
    className, // props.className mapped on to root element
  )}
/>;

CSS Variables

Use Fluent semantic color tokens directly.

Background

• --colorNeutralBackground1 - Lighter primary background
• --colorNeutralBackground2 - Middle background (uncommon)
• --colorNeutralBackground3 - Darker background
• --colorNeutralBackground4 - Very dark background (rarely used)

Border/Stroke

• --colorNeutralBackground4 - Existing panel-divider color
• --colorNeutralStroke1 - Standard border color for elements

Usage: border: 1px solid var(--colorNeutralStroke1);

Foreground/Text

Prefer using the Text component's foreground prop instead of setting text color in CSS.

• --colorNeutralForeground1 - Intense (primary text/headings)
• --colorNeutralForeground2 - Default body text color
• --colorNeutralForeground3 - Subtle/muted (secondary text)
• --colorNeutralForeground4 - Dim (disabled/placeholder text)
• --colorBrandForeground1 - Brand color
• --colorBrandForegroundLink - Link color

Interactive/States

Components own their hover, pressed, and selected states. Use the component API instead of introducing application-level interaction-color aliases.

Spacing - REQUIRED

NEVER use hardcoded pixel values or rem values for spacing values less than 32px. Always use these CSS variables:

• --spacingNone (0)
• --spacingXXS (2px)
• --spacingXS (4px)
• --spacingSNudge (6px)
• --spacingS (8px)
• --spacingMNudge (10px)
• --spacingM (12px)
• --spacingL (16px)
• --spacingXL (20px)
• --spacingXXL (24px)
• --spacingXXXL (32px)
• --spacingPagePadding - Special variable for horizontal page padding (adjusts by app container width, with a viewport-based fallback in the global stylesheet)

DO NOT use Fluent spacing variables that include "Horizontal" or "Vertical" in their names.

For pixel values 32px and above, you may use hardcoded values if necessary, but prefer using spacing variables where possible for consistency.

Border Radius

• --borderRadiusNone (0)
• --borderRadiusSmall (2px)
• --borderRadiusMedium (4px)
• --borderRadiusLarge (6px)
• --borderRadiusXLarge (8px)
• --borderRadius2XLarge (12px)
• --borderRadius3XLarge (16px)
• --borderRadius4XLarge (24px)
• --borderRadius5XLarge (32px)
• --borderRadius6XLarge (40px)
• --borderRadiusCircular (9999px)

Example CSS Patterns

Good - Uses Variables

.container {
  padding: var(--spacingL);
  background-color: var(--colorNeutralBackground1);
  border: 1px solid var(--colorNeutralStroke1);
  gap: var(--spacingM);
}

Bad - Hardcoded Values

.container {
  padding: 16px; /* WRONG - use var(--spacingL) */
  background-color: #f5f5f5; /* WRONG - use var(--colorNeutralBackground1) */
  font-size: 14px; /* WRONG - use Text component instead */
  color: #333; /* WRONG - use Text component instead */
}

Summary Checklist

Before submitting CSS edits, verify:

• [ ] Read corresponding .tsx file(s) that use this CSS
• [ ] All colors use Fluent semantic tokens
• [ ] All spacing uses --spacing* variables
• [ ] Component CSS file is named *.module.css; any app-level stylesheet edit stays within the foundational-style exception
• [ ] Classes combined with clsx when multiple are needed