Design System

Void Design System Rules

Purpose

Define standards for extending and implementing components in the Void design system.

Priority

High

Instructions

Component Architecture

ALWAYS follow component composition patterns from .amazonq/rules/frontend/component-patterns.md (ID: FOLLOW_COMPOSITION)

ALWAYS implement components in React with TypeScript (ID: REACT_TS)

ALWAYS separate Container and View components (ID: SEPARATE_CONCERNS)

Styling Standards

NEVER use CSS-in-JS solutions (styled-components, emotion, Material-UI) (ID: NO_CSS_IN_JS)

ALWAYS use vanilla CSS with CSS variables from @arcjr/void-tokens (ID: VANILLA_CSS)

ALWAYS use clsx for conditional classes (ID: USE_CLSX)

// Good - using clsx
import clsx from 'clsx';

const className = clsx(
  'void-button',
  variant && `void-button--${variant}`,
  disabled && 'void-button--disabled'
);

ALWAYS reference CSS variables from void-tokens (ID: VOID_CSS_VARS)

.void-button {
  background-color: var(--color-brand-azure);
  padding: var(--spacing-3) var(--spacing-5);
  border-radius: var(--border-radius-md);
  transition: all var(--transition-duration-fast) var(--transition-easing-ease);
}

NEVER import React in View components when using automatic JSX runtime (ID: NO_REACT_IMPORT_VIEWS)

// Good
import { memo } from 'react';

// Bad
import React, { memo } from 'react';

Component Documentation

ALWAYS include JSDoc comments in Component.tsx explaining (ID: JSDOC_REQUIRED):

• Component purpose and use cases
• Best practice usage patterns
• Examples of common scenarios

/**
 * Button component for user interactions
 * 
 * @example
 * // Primary button
 * <Button variant="primary"
 *   Click me
 * </Button>
 * 
 * @example
 * // Disabled state
 * <Button disabled>
 *   Cannot click
 * </Button>
 */

Storybook Integration

ALWAYS create Storybook CSF files co-located with components (ID: STORYBOOK_COLOCATED)

ALWAYS import component CSS in story files (ID: IMPORT_CSS_IN_STORIES)

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './index';
import './Button.css'; // Import CSS in story file

const meta: Meta<typeof Button> = {
  title: 'Void/Button',
  component: Button,
  tags: ['autodocs']
};

ALWAYS format stories with proper meta, args, and multiple variants (ID: WELL_FORMATTED_STORIES)

ALWAYS include stories for all component states and variants (ID: COMPREHENSIVE_STORIES)

File Structure

ALWAYS organize Void components following this structure (ID: VOID_STRUCTURE):

packages/void-components/src/Button/
├── index.ts              # Barrel export
├── Component.tsx         # Container with JSDoc
├── View.tsx             # Presentational
├── types.ts             # TypeScript types
├── Button.css           # Vanilla CSS with Void variables
├── Button.stories.tsx   # Storybook stories (imports CSS)
└── __tests__/
    └── Button.test.tsx  # Bun tests

CSS Organization

NEVER import CSS files directly into .tsx files except in .stories.tsx files (ID: NO_CSS_IMPORTS_TSX)

ALWAYS create separate CSS files for components (ID: SEPARATE_CSS)

ALWAYS use BEM-style naming with void- prefix (ID: VOID_BEM)

.void-button { }
.void-button--primary { }
.void-button--disabled { }
.void-button__icon { }

Build System

ALWAYS use Bun.build() programmatic API for bundling (ID: BUN_BUILD_API)

ALWAYS use separate functions for JS and CSS bundling (ID: SEPARATE_BUNDLE_FNS)

ALWAYS run type checking with tsc and tsc-alias after bundling (ID: TSC_AFTER_BUNDLE)

// build.ts pattern
async function bundle() {
  const result = await Bun.build({
    entrypoints: ['./src/index.ts'],
    outdir: './dist',
    target: 'browser',
    format: 'esm',
    sourcemap: 'external',
    minify: false,
    splitting: false,
    external: ['react', 'react-dom']
  });
}

async function bundleCSS() {
  const cssFiles = new Bun.Glob('src/**/*.css');
  const cssContent: string[] = [];
  for await (const file of cssFiles.scan('.')) {
    const content = await Bun.file(file).text();
    cssContent.push(`/* ${file} */\n${content}\n`);
  }
  await Bun.write('dist/index.css', cssContent.join('\n'));
}

Package Configuration

ALWAYS use modern "files" and "exports" fields in package.json (ID: MODERN_PKG_JSON)

ALWAYS set "type": "module" (ID: TYPE_MODULE)

ALWAYS export both JS and CSS in exports field (ID: EXPORT_JS_CSS)

{
  "type": "module",
  "files": ["dist"],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./styles": "./dist/index.css",
    "./package.json": "./package.json"
  }
}

Storybook Configuration

ALWAYS use Vite aliases to resolve workspace packages (ID: VITE_ALIASES)

// .storybook/main.ts
viteFinal: async (config) => {
  config.resolve.alias = {
    '@arcjr/void-tokens': resolve(__dirname, '../../void-tokens'),
    '@arcjr/void-css': resolve(__dirname, '../../void-css')
  };
  return config;
}

ALWAYS import void-tokens CSS in preview.ts (ID: TOKENS_IN_PREVIEW)

// .storybook/preview.ts
import '@arcjr/void-tokens/dist/css/void-tokens.css';

Testing

ALWAYS use Bun test runner with happy-dom (ID: BUN_TEST_HAPPYDOM)

ALWAYS use @testing-library/react for component tests (ID: TESTING_LIBRARY)

ALWAYS test accessibility attributes (aria-*, disabled, etc.) (ID: TEST_A11Y)

Error Handling

Components should handle edge cases gracefully and provide clear error messages when props are invalid.

Examples

Complete Void Component

// Component.tsx
import React from 'react';
import { pipeline } from '../utils/pipeline';
import ButtonView from './View';
import type { ButtonProps } from './types';

/**
 * Button component for primary user actions
 * 
 * Supports multiple variants and states. Use primary variant
 * for main actions, secondary for less important actions.
 * 
 * @example
 * <Button variant="primary"
 */
function Button(props: ButtonProps) {
  return <ButtonView {...props} />;
}

export default pipeline(React.memo)(Button);

// View.tsx
import { memo } from 'react';
import clsx from 'clsx';
import { pipeline } from '../utils/pipeline';
import type { ButtonProps } from './types';

function ButtonView({ variant = 'primary', disabled, children, onClick }: ButtonProps) {
  return (
    <button
      className={clsx(
        'void-button',
        `void-button--${variant}`,
        disabled && 'void-button--disabled'
      )}
      disabled={disabled}
     
      aria-disabled={disabled}
    >
      {children}
    </button>
  );
}

export default pipeline(memo)(ButtonView);

// Button.css
.void-button {
  padding: var(--spacing-3) var(--spacing-5);
  border-radius: var(--border-radius-md);
  font-family: var(--font-family-base);
  cursor: pointer;
  border: none;
  transition: all var(--transition-duration-fast) var(--transition-easing-ease);
}

.void-button--primary {
  background-color: var(--color-brand-azure);
  color: var(--color-base-white);
}

.void-button--disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './index';
import './Button.css';

const meta: Meta<typeof Button> = {
  title: 'Void/Button',
  component: Button,
  tags: ['autodocs']
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Button'
  }
};

Converted and distributed by TomeVault — claim your Tome and manage your conversions.