Why This Design System Exists

Building Joomla sites for multiple customers means repeating the same decisions — typography, spacing, color, interactive patterns — project after project. JCrafts solves this by codifying those decisions once, in a parent template that all customer sites inherit from.

This design system serves two audiences:

• Developers building child templates — understand what is already provided, what to override for branding, and how to extend with custom components.
• Developers maintaining the parent template — document decisions, prevent accidental regressions, and test components in isolation.

The goal is a single source of truth: change a design token here, and every child template that inherits from the parent benefits automatically.

Scope

This design system covers:

• The full set of design tokens (colors, typography, spacing, sizes)
• Atomic HTML elements — how native block, inline, and form elements are styled by default
• Reusable components — layout primitives, navigation, teasers, compositions, and Joomla-specific elements
• Theming API — the brand token layer that child templates override per customer

It does not document Joomla core behavior, module positions, or PHP template logic.

How the System Is Structured

JCrafts is layered. Each layer builds on the one below it:

1. Design Tokens — primitive values (hex colors, rem sizes, font stacks) defined once in src/assets/tokens/ and compiled via Terrazzo into CSS custom properties. Everything else references tokens, never raw values.
2. Brand Tokens — a thin override layer that maps three semantic roles (primary, secondary, accent) and font families to the primitive palette. This is the only layer a child template needs to touch for branding.
3. Atoms — the default styling applied to native HTML elements (headings, paragraphs, lists, forms, code blocks). No classes required.
4. Components — reusable, class-based patterns built from tokens. Each is documented here with variants, usage examples, and accessibility notes.

Component Documentation

Each component lives in src/_includes/components/. A *.config.js file next to any component template causes it to be auto-picked up and displayed here. The config defines the component title, preview variant, and example context data.

Components without a config file (e.g. internal utilities) are intentionally undocumented.

Child Template Relationship

A child template declares <parent>jcrafts</parent> in its Joomla manifest. It inherits all compiled CSS and layouts from the parent and only ships brand token overrides plus any customer-specific component overrides. See Child Template Setup for the full workflow.

Where to Start

For a new child template

1. Read Brand Tokens to understand which tokens to override.
2. Follow the Child Template Setup guide to scaffold the child template repo.
3. Browse Layout components to understand available layout primitives before writing custom CSS.

For exploring the system

1. Start with Design Tokens for a complete reference of all available CSS custom properties.
2. Check Core Colors to see the full color palette.
3. Browse components by category in the sidebar — each page shows live previews and HTML examples.

For accessibility

See the Accessibility page for the system-wide approach to keyboard navigation, ARIA patterns, color contrast, and motion.