Fractal Component Library

A modern component library built with Fractal, featuring Style Dictionary for design token management and automated documentation generation.

Context-Based Design Systems (CBDS) Alignment

This starter kit is designed to align with Southleft's Context-Based Design Systems approach—a new paradigm where design systems encode not just how something looks, but what it means, how it behaves, and when it should be used.

How This Starter Kit Embodies CBDS Principles

Structured Context Through Design Tokens Style Dictionary transforms design decisions into structured, semantic tokens that carry meaning and intent through every phase of development. These aren't just color values—they're contextual decisions about when and how to use them.

Automated Documentation as Living Context The build scripts automatically generate documentation from token sources, ensuring that the intent behind design decisions is always current and accessible. This creates a single source of truth that both humans and AI can understand.

Semantic Token Architecture The token system uses semantic naming (background-primary, content-default, border-subtle) that describes purpose rather than appearance. This context travels with the component, enabling smarter handoffs and better automation.

Theme Variations as Contextual States The theme variations (default, inverted, subtle) demonstrate how the same components adapt to different contexts while maintaining their structural integrity and intent.

Ready for AI-Driven Workflows With structured tokens, clear documentation, and semantic naming conventions, this system is prepared for the next generation of AI-assisted development where context enables more intelligent code generation and design-to-code workflows.

---

This component library is built using Fractal and enhanced with Style Dictionary for robust design token management.

What's New in This Version

This starter kit includes several enhancements over the basic Fractal setup:

Design Token System

• Style Dictionary Integration: Automated design token generation from JSON source files
• Multi-theme Support: Includes default, inverted, and subtle theme variations
• Semantic Tokens: Context-aware design tokens for consistent theming
• SCSS Variables: Tokens are compiled to CSS custom properties and SCSS variables

Automated Documentation

• Token Documentation: Auto-generated documentation pages for all design tokens
• Live Examples: Interactive demos showing token usage and theme variations
• Build Scripts: Automated generation of documentation from token sources

Build System Enhancements

• Gulp 5 with ESM: Modern build pipeline via gulpfile.mjs
• Token Build Pipeline: npm run build:tokens compiles design tokens to CSS/SCSS/JSON
• Documentation Generation: Single build script (docs/scripts/docs-build.js) generates all token documentation
• Full Build Process: npm run build runs the complete pipeline: tokens → styles → docs → static export

Requirements

You'll need a supported LTS version of Node. Fractal may work on unsupported versions, but there is no active support from Fractal and new features may not be backwards compatible with EOL versions of Node.

This component library utilizes the following dependencies:

• Node.js
• Fractal
• Style Dictionary - Design token management
• Gulp - Build automation
• Sass - CSS preprocessing

Getting started

Install and configure

1. Install dependencies:

npm install

2. Update site.config.js in the project root with your project details:

module.exports = {
  prefix: 'sl',                          // Token prefix used in CSS custom properties
  title: 'Your Project Name',            // Displayed in the Fractal UI header
  logo: '/src/images/logo.svg',          // Logo shown in the Fractal UI
  favicon: '/images/favicon.png',        // Browser tab favicon
};

3. Start the development server:

npm run dev

This launches the Fractal server on port 3333 with browser sync and Gulp watching for file changes.

Available Commands

# Development
npm run dev              # Start Fractal server (port 3333) + Gulp watch (parallel)
npm run fractal:start    # Start Fractal server only with browser sync
npm run gulp:watch       # Run Gulp watch only

# Build
npm run build            # Full build: tokens → gulp → docs → fractal export
npm run build:tokens     # Rebuild design tokens only
npm run build:docs       # Regenerate documentation pages only
npm run gulp:build       # Compile SCSS, JS, images, fonts, docs CSS
npm run fractal:build    # Build static Fractal export only

Design Token Structure

The design tokens are organized in the /src/tokens directory:

tokens/
├── base/                # Core design tokens
│   ├── animations.json  # Duration and timing functions
│   ├── borders.json     # Border widths, radii, styles
│   ├── breakpoints.json # Responsive breakpoint values
│   ├── colors.json      # Color palette definitions
│   ├── icons.json       # Icon definitions
│   ├── layout.json      # Container and layout values
│   ├── opacity.json     # Opacity scale
│   ├── shadows.json     # Box shadow definitions
│   ├── spacing.json     # Spacing scale
│   ├── typography.json  # Font families, sizes, weights
│   └── z-index.json     # Z-index scale
├── theme/               # Theme-specific overrides
│   ├── default/         # Default (light) theme
│   ├── inverted/        # Dark/inverted theme tokens
│   └── subtle/          # Subtle theme variant
└── tokens-config.js     # Style Dictionary configuration

Tokens are compiled to:

• /src/styles/tokens/ - SCSS variables
• /src/json/tokens.json - JSON token map
• /public/css/theme.css - CSS custom properties for runtime theming

Installing globally

npm i -g @frctl/fractal

This will also give you global access to the fractal command which you can use to scaffold a new Fractal project with fractal new.

The downside is that it's then difficult to use different Fractal versions on different projects.