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.