Guide

Getting Started

Everything you need to start building with the Entangle Design System. From install to first component in under five minutes.

01 · Overview

What you're looking at

The Entangle Design System is the shared visual language behind everything Entangle ships. It lives inside a pnpm monorepo and is entirely token-driven: every colour, space, radius, shadow, and motion value resolves to a CSS custom property.

Themes are expressed as data attributes on the HTML root. Switch between dark and light mode and every token updates automatically — no runtime JS, no class toggling on individual elements.

02 · Install

Install

bash

# Inside the Entangle monorepo — packages resolve via workspace protocol
pnpm add @entangle-hq/ui@workspace:* @entangle-hq/tokens@workspace:*

03 · Setup

Setup

1. Import the token CSS

Add this to your root layout. It gives you all CSS custom properties — colours, spacing, radii, shadows, motion, and fonts.

tsx

import "@entangle-hq/tokens/css";

2. Import global styles

If you are using @entangle-hq/ui components, pull in the base styles:

tsx

import "@entangle-hq/ui/styles.css";

3. Set the theme

Apply a theme class to your HTML root element. Use the no-flash boot script to prevent FOUC:

html

<html class="dark">
  <!-- or use the no-flash boot script: -->
  <script>
    (function() {
      try {
        var t = localStorage.getItem('entangle-theme');
        if (t !== 'light' && t !== 'dark') {
          t = window.matchMedia('(prefers-color-scheme: light)').matches
            ? 'light' : 'dark';
        }
        document.documentElement.classList.add(t);
      } catch(e) {
        document.documentElement.classList.add('dark');
      }
    })();
  </script>

4. Configure Tailwind

Tell Tailwind to scan the UI package for utility classes:

css

@import "tailwindcss";
@source "../../../packages/ui/src";

04 · First Component

Your first component

With tokens and styles imported, you can compose UI components immediately:

tsx

import { Button, Card, CardBody, Stack } from "@entangle-hq/ui";

export function Demo() {
  return (
    <Card>
      <CardBody>
        <Stack gap="md">
          <h2>Welcome</h2>
          <Button>Get started</Button>
          <Button variant="secondary">Learn more</Button>
        </Stack>
      </CardBody>
    </Card>
  );
}

05 · Architecture

Architecture overview

The Entangle monorepo is structured as a set of packages consumed by applications:

Packages

@entangle-hq/tokensCSS variables, Tailwind preset, token build pipeline

@entangle-hq/uiReact components (Button, Input, Card, Container, Stack)

@entangle-hq/iconsLucide subset (planned)

@entangle-hq/emailReact Email templates (planned)

Applications

apps/webentangle.com.au

apps/docsThis site (weave.entangle.com.au)

06 · Principles

Key principles

01Token-first — Every visual decision flows from tokens. No hardcoded colours, spacing, or typography.

02Glass over shadow — Translucent surfaces with backdrop-blur, not opaque cards with drop shadows.

03Mono for action — Buttons, badges, tags, and navigation use monospace uppercase with tight tracking.

04Earned hierarchy — Display type is reserved for headlines. Body stays at 16px. Earn size through content importance.

05Dark by default — Dark mode is primary. Light mode is a mapped derivative, not an afterthought.