accelint-design-foundation

name	accelint-design-foundation
description	Use when styling components or elements with @accelint/design-foundation or @accelint/design-toolkit packages, or when users say "style this", "add styling", "theme this component", "add colors", "add spacing", "CSS modules", "setup design foundation", "@variant", or when working with .module.css files. Provides opinionated Tailwind conventions including semantic tokens, custom spacing scale, outline-based borders, variant system, and CSS module setup guidance.
license	Apache-2.0
metadata	{"author":"accelint","version":"1.0.0"}

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:

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:

{
  "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:

/* If project has custom CSS entrypoint (defined in package.json imports): */
@reference '#globals';

@layer components.l1 {
  .button {
    @apply px-m py-xs;
  }
}

/* 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):

/* 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:

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 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 (~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 (~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 (~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 (~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 (~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 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:

@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:

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:

// ✅ 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:

// ✅ 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