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:

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 {children};
}

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:

@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 (
    
      
        {name}
      
      
        {email}
        {role}
      
    
  );
}

Inline classes only for one-off overrides:

// ✅ Correct - CSS module + inline override for specific instance
 {/* One-off spacing adjustment */}

// ❌ Wrong - all styling inline

  {name}

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 (
    
      Click me
    
  );
}

// ❌ 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
• bg-info-muted - Info message backgrounds
• bg-advisory-muted - Warning message backgrounds
• bg-critical-muted - Error/danger message backgrounds
• bg-normal-muted - Success message backgrounds

Foreground tokens (fg-*):

• fg-primary-bold - Primary text (headlines, body text)
• fg-primary-muted - Subtle text (captions, secondary content)
• fg-inverse-bold - Text on dark/colored backgrounds
• fg-accent-primary-bold - Interactive text/links
• fg-critical-bold - Error/danger text

Outline tokens (outline-*):

• outline-interactive - Interactive outlines (buttons, inputs)
• outline-static - Static outlines (borders, dividers)
• outline-info-bold - Info state outlines
• outline-advisory-bold - Warning state outlines
• outline-critical-bold - Error/danger state outlines

Token fallback pattern:

// ✅ Preferred - semantic tokens
Content

// ⚠️  Acceptable but rare - domain/primitive fallback for edge cases

  {/* Use only when design exceeds system */}

// ❌ Wrong - using fallbacks when semantic tokens exist

  {/* Should use bg-surface-default fg-primary-bold */}

Spacing Scale

Eight-step semantic scale: xxs → xs → s → m → l → xl → xxl → oversized

Think semantic meaning, not pixels. m means "medium for this context", not a specific pixel value.

CSS module usage:

.button {
  @apply px-m py-xs; /* ✅ Semantic spacing - preferred */
}

.card {
  @apply p-m space-y-s; /* ✅ Semantic scale for consistency */
}

/* ⚠️  Acceptable but rare - numeric fallback for edge cases */
.nonStandardLayout {
  @apply p-13; /* 13px exactly - use only for non-conforming designs */
  /* Note: p-1 = 1px (not 4px like vanilla Tailwind) */
}

Spacing fallback pattern:

• Preferred: Use semantic scale (p-m, gap-s, mb-l)
• Fallback: Numeric classes available with 1:1 relationship (p-1 = 1px, p-12 = 12px)
• When to use numeric: Only for non-conforming designs where semantic scale do

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gohypergiant
• Source: gohypergiant/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.