accelint-design-foundation

# Accelint Design Foundation Expert knowledge for styling with `@accelint/design-foundation` and `@accelint/design-toolkit` — opinionated Tailwind conventions that differ from vanilla implementations. ## NEVER Do When Styling with Design Foundation - **NEVER use numeric spacing classes as first choice** - Strongly prefer the semantic scale: `p-xxs`, `gap-m`, `m-l`. Numeric classes like `p-4`, `gap-6` work with a 1:1 relationship (`p-1` = 1px, NOT 4px like vanilla Tailwind), but should only be used for rare cases where implementing non-conforming designs. The semantic scale provides design system consistency. - **NEVER use manual theme handling with raw color values** - Avoid `dark:bg-gray-900` or `className={theme === 'dark' ? 'bg-black' : 'bg-white'}`. Use semantic color classes like `bg-surface-default` and `fg-primary-bold` that automatically adapt to light/dark themes. - **NEVER use borders for sizing elements** - Use `outline` instead of `border` classes. Borders add to element dimensions (breaks layouts), while outlines overlay without affecting size. Elements should size consistently based on content and padding only. - **NEVER use arbitrary Tailwind variants** - Arbitrary values like `hover:[&>svg]:opacity-50` break the design system. Use supported React Aria variants or conditional class rendering with `clsx`. - **NEVER bypass CSS layers when styling components** - Use `@layer components.l1`, `@layer components.l2` for cascade hierarchy. Bypassing layers causes specificity wars and makes overrides unpredictable. - **NEVER use primitive/domain tokens as first choice** - Strongly prefer semantic tokens (`bg-surface-default`, `fg-primary-bold`) in components. The utility classes (`bg-*`, `fg-*`, `icon-*`, `outline-*`) provide fallback access to `domain-*` and `primitive-*` tokens for rare cases where designs go beyond the design system, but this should be exceptional. Semantic tokens provide theming flexibility and design system consistency. - **NEVER use inline Tailwind classes for component styling** - Component styles belong in CSS modules, not inline className props. Inline Tailwind should only be used for minor one-off overrides. Using inline classes for all component styling creates unmaintainable code and loses the benefits of CSS modules (scoping, organization, reusability). - **NEVER use multiple @apply directives in a single CSS rule** - Group all Tailwind classes into a single `@apply` statement. Multiple `@apply` directives prevent Tailwind IDE plugins from sorting classes and identifying issues. Write `@apply bg-surface-default outline-1 outline-interactive p-m;` not separate `@apply` lines. - **NEVER use attribute selectors for variants in CSS modules** - Use `@variant` directive blocks, not attribute selectors like `[data-size="small"]`. Write `@variant size-small { @apply p-s; }` not `.button[data-size="small"] { @apply p-s; }`. The `@variant` directive automatically applies styles when the matching data attribute is present. - **NEVER use Tailwind's default theme values** - The design foundation removes and replaces Tailwind defaults. Relying on default shadows, font sizes, or colors will break. Use only the semantic classes provided by the design system. - **NEVER omit @reference directive in CSS modules** - Every CSS module file must include `@reference '#globals';` (if custom entrypoint exists) or `@reference '@accelint/design-foundation/styles';` at the top. Without this, semantic tokens and @variant blocks are undefined, causing build errors. - **NEVER skip PostCSS configuration** - The `@accelint/postcss-tailwind-css-modules` plugin is required in `postcss.config.mjs`. Without it, named group selectors (like `group-hover/button:`) and @variant selectors fail to resolve in CSS modules. - **NEVER import clsx directly from 'clsx' package** - Always import from `@accelint/design-foundation/lib/utils` instead: `import { clsx } from '@accelint/design-foundation/lib/utils';`. The design foundation re-exports clsx with additional type support and design system integration. Importing directly bypasses these enhancements. ## Before Styling a Component, Ask Apply these tests to ensure styling aligns with the design system: ### Theme Compatibility - **Will this work in both light and dark themes?** Use semantic color tokens that adapt automatically. Test by toggling between `@variant light` and `@variant dark`. - **Am I using raw color values?** If yes, replace with semantic tokens. Raw values don't theme. ### Token System - **Am I using the correct token type?** Strongly prefer semantic tokens (`bg-surface-default`, `fg-primary-bold`). Only use `domain-*` or `primitive-*` fallbacks for exceptional cases where design goes beyond the system. - **Is there a semantic token for this?** Check the token catalog first. If no semantic token exists and the design genuinely requires it, fallback to `domain-*` or `primitive-*` is acceptable but rare. ### Token Selection Framework When choosing a token, follow this decision tree: 1. **Identify element purpose** - Is this a surface, text, icon, or outline? 2. **Determine hierarchy** - Primary, secondary, or tertiary emphasis? 3. **Consider state** - Default, hover, active, disabled? 4. **Check status** - Info, success, warning, danger? **Example:** "I need text color for a primary heading" → Purpose: text (`fg-*`) → Hierarchy: primary with emphasis (`primary-bold`) → Result: `fg-primary-bold` **Example:** "I need background for an interactive button in hover state" → Purpose: background (`bg-*`) → State: interactive hover (`interactive-bold-hover`) → Result: `bg-interactive-bold-hover` ### Spacing System - **Does this spacing value exist in the semantic scale?** Use `xxs/xs/s/m/l/xl/xxl/oversized` scale. If a value isn't in the scale, question whether it's needed or use the closest semantic value. - **Need a non-standard spacing value?** Numeric classes (`p-1`, `m-12`) work with 1:1 relationship (p-1 = 1px, NOT 4px), but only use for rare non-conforming design cases. Semantic scale is strongly preferred for consistency. ### Variant Usage - **Can this be expressed with data attributes?** Use `data-color="info"` with supported variants instead of arbitrary classes. - **Am I overriding Design Toolkit components correctly?** Use `className` or `classNames` props, not custom CSS files. ### Layout Impact - **Will outlines work here or do I need borders?** Outlines work for most cases. Borders are only needed when the border must affect layout dimensions. ### Styling Approach - **Should this be in CSS modules or inline?** Component styles belong in CSS modules (.module.css). Only use inline Tailwind classes for minor one-off overrides or adjustments. - **Is this a reusable component or one-off instance?** Reusable components require CSS modules. One-off instances can use inline classes for small tweaks. ### Setup Verification - **Is PostCSS configured correctly?** Check that `@accelint/postcss-tailwind-css-modules` plugin is in `postcss.config.mjs`. Without it, named groups and @variant selectors won't work in CSS modules. - **Does every CSS module have @reference?** Each `.module.css` file must reference either `'#globals'` (custom entrypoint) or `'@accelint/design-foundation/styles'` at the top. - **Is the CSS entrypoint imported first?** Custom globals.css (or design-foundation/styles) must be the first import in the root layout. ## Setup Requirements **CRITICAL: Design foundation requires specific PostCSS and CSS module configuration to work correctly.** ### PostCSS Configuration Create or update `postcss.config.mjs` in project root: ```javascript export default { plugins: { '@tailwindcss/postcss': {}, '@accelint/postcss-tailwind-css-modules': {}, // Required for CSS modules }, }; ``` **Why:** The `@accelint/postcss-tailwind-css-modules` plugin fixes named group resolution in CSS module selectors (e.g., `group-hover/button:`) and @variant selectors. Without it, these selectors fail to resolve correctly in CSS module files. ### Package.json Imports (If Custom CSS Entrypoint Exists) If the project implements a custom CSS entrypoint for token/utility configuration: ```json { "imports": { "#globals": "./src/styles/globals.css" } } ``` **Purpose:** Allows CSS modules to reference the custom entrypoint via `@reference '#globals';` ### CSS Module Reference Pattern **Every CSS module file must include a reference directive:** ```css /* If project has custom CSS entrypoint (defined in package.json imports): */ @reference '#globals'; @layer components.l1 { .button { @apply px-m py-xs; } } ``` ```css /* If NO custom CSS entrypoint, reference design-foundation directly: */ @reference '@accelint/design-foundation/styles'; @layer components.l1 { .button { @apply px-m py-xs; } } ``` **Why:** The @reference directive imports the design system's tokens, utilities, and variant definitions. Without it, semantic tokens and @variant blocks are undefined. ### Custom CSS Entrypoint (Optional) If implementing custom tokens or utilities, create a CSS entrypoint (e.g., `src/styles/globals.css`): ```css /* Import design foundation base */ @import "@accelint/design-foundation/styles"; /* Add custom token overrides or utilities here */ @theme { --custom-brand-color: #ff0000; } ``` **Then:** Import this file as the **first import** in your root layout component: ```tsx import './styles/globals.css'; // First import import { ReactNode } from 'react'; export default function RootLayout({ children }: { children: ReactNode }) { return <html>{children}</html>; } ``` ## How to Use This skill uses **progressive disclosure** to minimize context usage: ### 1. Start with Core Patterns (SKILL.md) Follow the styling patterns and token usage below for consistent implementation. ### 2. Reference Token Catalog (AGENTS.md) Load [AGENTS.md](AGENTS.md) for quick reference of available tokens, spacing scale, and variant patterns. ### 3. Load Detailed References as Needed **MANDATORY loading triggers** - Load these references in specific scenarios: **Setting up design foundation for the first time:** - **MANDATORY**: Load [references/setup.md](references/setup.md) (~8.9K) completely when user says "setup design foundation", "configure design foundation", "install design foundation", or encounters build errors like "undefined variable" or "@variant not found" - **Do NOT Load**: token-reference.md, variant-system.md, spacing-scale.md, migration-guide.md **Choosing tokens or understanding token hierarchy:** - **MANDATORY**: Load [references/token-reference.md](references/token-reference.md) (~6.5K) when uncertain which semantic token to use or when user needs complete token catalog - **Do NOT Load**: setup.md (unless build errors), migration-guide.md (unless migrating) **Working with @variant system or component variants:** - **MANDATORY**: Load [references/variant-system.md](references/variant-system.md) (~5.8K) when implementing data attribute variants or working with React Aria states - **Do NOT Load**: setup.md (unless build errors), migration-guide.md (unless migrating) **Understanding spacing scale or numeric fallbacks:** - **MANDATORY**: Load [references/spacing-scale.md](references/spacing-scale.md) (~8.5K) when confused about semantic vs numeric spacing or need complete spacing catalog - **Do NOT Load**: token-reference.md (unless also working with colors), setup.md (unless build errors) **Migrating from vanilla Tailwind:** - **MANDATORY**: Load [references/migration-guide.md](references/migration-guide.md) (~4.2K) when converting existing Tailwind code to design foundation conventions - **Do NOT Load**: Other references unless specific issues arise after migration **Troubleshooting build errors or setup issues:** - **MANDATORY**: Load [references/setup.md](references/setup.md) completely when encountering errors like "undefined variable", "@variant not found", "group-hover/button: not working" - **Do NOT Load**: Other references until setup is confirmed working ## Styling Patterns ### CSS Modules for Component Styling **Default approach: Component styles in CSS modules with @apply directives.** **user-card.module.css:** ```css @layer components.l1 { /* ✅ Single @apply per rule - enables IDE plugin support */ .card { @apply bg-surface-default outline-1 outline-interactive shadow-elevation-raised-muted p-m; } .header { @apply flex items-center justify-between mb-s; } .title { @apply fg-primary-bold text-body-l; } .content { @apply space-y-xs mb-m; } .email { @apply fg-primary-bold text-body-m; } .role { @apply fg-primary-muted text-body-s; } .actions { @apply flex gap-s; } } /* ❌ Wrong - multiple @apply directives break IDE plugins */ /* .card { @apply bg-surface-default; @apply outline-1 outline-interactive; @apply shadow-elevation-raised-muted; @apply p-m; } */ ``` **user-card.tsx:** ```tsx import styles from './user-card.module.css'; export function UserCard({ name, email, role }) { return ( <article className={styles.card}> <header className={styles.header}> <h3 className={styles.title}>{name}</h3> </header> <div className={styles.content}> <p className={styles.email}>{email}</p> <p className={styles.role}>{role}</p> </div> </article> ); } ``` **Inline classes only for one-off overrides:** ```tsx // ✅ Correct - CSS module + inline override for specific instance <UserCard className="mb-xl" /> {/* One-off spacing adjustment */} // ❌ Wrong - all styling inline <div className="bg-surface-default outline-1 outline-interactive shadow-elevation-raised-muted p-m"> <h3 className="fg-primary-bold text-body-l">{name}</h3> </div> ``` **Conditional classes with clsx:** ```tsx // ✅ Correct - import clsx from design foundation import { clsx } from '@accelint/design-foundation/lib/utils'; import styles from './Button.module.css'; export function Button({ variant, isActive }) { return ( <button className={clsx(styles.button, isActive && styles.active)}> Click me </button> ); } // ❌ Wrong - importing directly from clsx package import clsx from 'clsx'; ``` ### Token Categories **Background tokens (`bg-*`):** - `bg-surface-default` - Primary surface (page/card background) - `bg-surface-raised` - Raised/elevated surface - `bg-interactive-bold` - Primary action background