Get Started

• 1: Introduction
• 2: Install AngularCSS
• 3: Build Your First Component
• 4: Customization
• 5: Compatibility and upgrades

1 - Introduction

AngularCSS provides HTML-first styles and focused interface components for AngularTS. Most interface elements are semantic HTML styled directly by CSS. TypeScript components are reserved for interactions that native HTML, CSS, and AngularTS do not already provide.

AngularCSS is a customization system, not a design system. It provides a stable functional baseline and presentation controls; the application owns its brand, visual language, and product-specific design.

<button variant="outline">Save changes</button>

No directive runs for this button. The browser owns activation and disabled state, AngularTS owns application commands, and CSS targets the native element and authored variant directly.

Three layers

1. HTML owns semantics. Use button, input, dialog, nav, table, and other native elements whenever they fit the interaction.
2. AngularTS owns application state. Use ng-model, ng-click, validation, interpolation, and structural directives for values and business behavior.
3. AngularCSS fills genuine interaction gaps. Components add composite keyboard navigation, focus management, disclosure coordination, and dynamic accessibility relationships only when the first two layers are insufficient.

This boundary prevents a component from creating a second form model, template engine, validation system, or styling-state mirror over AngularTS and the browser.

HTML-first composition

Complex components are composed from named parts rather than hidden templates:

<details class="disclosure">
  <summary>Account settings</summary>
  <section>
    <label for="display-name">Display name</label>
    <input id="display-name" ng-model="profile.name" />
  </section>
</details>

You control the elements, content, AngularTS expressions, and application CSS. Each catalog page documents the authored HTML and any runtime behavior it needs.

What is included

• 67 documented entries split into foundations, elements, patterns, focused behavioral components, and recipes.
• TypeScript declarations generated from the canonical source.
• A compiled CSS entrypoint and a DTCG 2025.10 customization token resolver.
• Local UMD and ESM builds.
• Browser-tested demos isolated from the documentation shell in iframes.

Next step

Install AngularCSS and connect the angular.css module to an AngularTS application.

2 - Install AngularCSS

AngularCSS is distributed as an npm package. Its behavioral components require AngularTS. Install both packages locally:

npm install @angular-wave/angular.ts @angular-wave/angular.css

No CDN is required. The package includes ESM, UMD, CSS, and TypeScript declaration outputs.

Stylesheet-only setup

Native elements, patterns, foundations, and recipes need only the compiled AngularCSS stylesheet:

@import "@angular-wave/angular.css/dist/angular.css";

<button variant="outline">Save</button>

These entries register no AngularCSS directive. Add AngularTS for application bindings, and load AngularCSS JavaScript with the angular.css dependency when using behavioral components such as tabs or comboboxes.

Bundler setup

Import AngularTS before AngularCSS so the runtime exists when AngularCSS registers its directives. Import the compiled stylesheet once in your application entrypoint:

import { angular } from "@angular-wave/angular.ts";
import "@angular-wave/angular.css";
import "@angular-wave/angular.css/dist/angular.css";

angular.createModule("app", ["angular.css"]);

Then attach your application module to an HTML root:

<main ng-app="app">
  <button>Save</button>
</main>

The package registers one AngularTS module named angular.css. Your application should depend on that module; do not register individual AngularCSS directives again.

Local script setup

Applications without a bundler can copy the two UMD files and the compiled CSS into their own static asset directory. Serve all three from the same origin:

<link rel="stylesheet" href="/vendor/angularcss/angular.css" />
<script src="/vendor/angular/angular-ts.umd.js"></script>
<script src="/vendor/angularcss/angular-css.umd.js"></script>

<div ng-app="angular.css">
  <button>Save</button>
</div>

Load AngularTS first. The documentation examples use this local script order and never fetch runtime code or styles from a CDN.

Application styles

Load AngularCSS before application styles so your custom properties and rules can configure its defaults:

@import "@angular-wave/angular.css/dist/angular.css";

@layer components {
  :root {
    --primary: #175cd3;
    --radius: 0.375rem;
  }

  button[variant="outline"] {
    border-color: var(--border);
    background: transparent;
  }
}

The published CSS is compiled and has no framework dependency. See Customization for the complete CSS-variable and DTCG token contract.

Verify the installation

Render a button and inspect it in browser developer tools:

<button variant="secondary">Installed</button>

The element should retain its native attributes. If it remains unstyled, verify the CSS import. Behavioral components additionally require the AngularTS script order and the angular.css module dependency.

TypeScript

The package ships declarations under @types. TypeScript resolves them from the package’s types field; no separate DefinitelyTyped package is needed.

Next step

Build your first component with semantic HTML and AngularTS state.

3 - Build Your First Component

This page builds an accordion with native details and summary. The browser owns disclosure; AngularTS owns the application value inside the panel.

Add the HTML

<section ng-app="app">
  <section aria-label="Profile sections">
    <details name="profile-sections" open>
      <summary>Profile</summary>
      <div>
        <label for="display-name">Display name</label>
        <input id="display-name" ng-model="profile.name" />
        <output>Preview: {{ profile.name || "Unnamed" }}</output>
      </div>
    </details>
  </section>
</section>

Each direct child is a native disclosure item. The browser creates the trigger relationship and owns open state, focus, and keyboard activation.

Create the application module

import { angular } from "@angular-wave/angular.ts";
import "@angular-wave/angular.css";
import "@angular-wave/angular.css/dist/angular.css";

angular.createModule("app", ["angular.css"]);

No controller is required for this example. ng-model creates the profile name binding in the application scope, and interpolation updates the preview. AngularCSS does not parse or store that value.

Test the result

1. Press Tab until the accordion trigger receives focus.
2. Press Enter or Space to open and close the panel.
3. Enter a display name and confirm the preview updates.
4. Inspect the details element’s native open state.

Add multiple panels

Add another sibling details with the same name to make the group exclusive. Omit name when several panels may remain open:

<section aria-label="Sections">
  <details>...</details>
  <details>...</details>
</section>

Next step

Customize components, then browse the complete accordion reference.

4 - Customization

AngularCSS is a customization system, not a design system. It supplies a consistent functional baseline and stable presentation controls. Your application still decides its brand, visual language, content hierarchy, and product-specific composition.

Every browser-facing customization control is a CSS custom property. Consumers do not need a token compiler, Tailwind, Sass, JavaScript, or an AngularCSS build step to change the defaults.

Load order

Load AngularCSS before application styles. The bundle declares this low-to-high layer order: base, angularcss.tokens, angularcss.components, components, and utilities.

@import "@angular-wave/angular.css/angular.css";

@layer components {
  :root {
    --primary: #175cd3;
    --primary-foreground: #fff;
    --radius: 0.375rem;
  }
}

Unlayered application rules remain above normal layered declarations. Use the public components layer for reusable application rules and utilities for local exceptions.

Customization token format

AngularCSS authors its defaults as Design Tokens Community Group 2025.10 token files. The package exports the resolver at @angular-wave/angular.css/customization-tokens for design, documentation, and translation tools.

The generated CSS variables remain the runtime API. The DTCG files improve interoperability and validation; they do not turn AngularCSS into a design system or require applications to adopt a token tool.

The customization families are:

• Colors: semantic surfaces, content, actions, states, charts, sidebar, and compatibility palettes.
• Spacing: the base rhythm and an explicit spacing scale.
• Typography: font families, sizes, weights, and line heights.
• Shadows: elevation values for controls, panels, menus, and dialogs.
• Radii: control, surface, overlay, and fully rounded geometry.
• Sizing: control heights, icon sizes, and the minimum comfortable pointer target.
• Borders and focus: shared widths and visible keyboard-focus geometry.
• Motion: shared durations and easing curves.

Global customization

Set semantic variables on :root to configure the entire application:

:root {
  --background: #fff;
  --foreground: #17202a;
  --primary: #175cd3;
  --primary-foreground: #fff;
  --border: #d0d5dd;
  --input: #98a2b3;
  --ring: #528bff;

  --spacing: 0.25rem;
  --font-sans: Inter, system-ui, sans-serif;
  --text-sm: 0.875rem;
  --font-weight-medium: 500;
  --shadow-md: 0 4px 8px rgb(16 24 40 / 12%);
  --radius: 0.375rem;
}

Components consume semantic variables such as --background, --primary, and --border. Palette variables such as --blue-9 remain available when an application needs a concrete value, but component rules do not require a specific brand palette.

Scoped customization

Custom properties inherit, so an application region can use different presentation settings without copying component selectors:

.operations-console {
  --spacing: 0.2rem;
  --radius: 0.25rem;
  --size-control-md: 2rem;
  --shadow-md: 0 2px 5px rgb(16 24 40 / 10%);
}

Use scoped values for embedded tools, dense administrative areas, or gradual brand migrations. Keep focus indicators and pointer targets usable when reducing density.

Density contexts

Set data-density on the application root or a subtree to apply a coordinated spacing and control-geometry preset. The attribute changes the same public variables that applications can set directly.

<section data-density="compact">
  <!-- Dense administrative workspace -->
</section>

compact favors information-dense pointer workflows. comfortable increases spacing and target sizes for lower-density forms and touch-oriented areas. The default context remains between the two. Applications can override any mapped variable after the preset.

Contrast contexts

AngularCSS responds to prefers-contrast: more by strengthening borders, control outlines, and focus rings. Use data-contrast="more" to request the same treatment for a subtree independent of the operating-system preference:

<main data-contrast="more">...</main>

The context maps semantic variables and therefore follows customized light and dark colors instead of imposing a separate palette.

Print contexts

Print styles remove shadows and motion, preserve readable light surfaces, and let scrollable tables and data regions expand. Mark application-only controls with data-print="exclude"; mark print-only content with data-print="only".

<button data-print="exclude">Edit</button>
<p data-print="only">Generated from the current customer record.</p>

These attributes express document intent in HTML and work across components.

Dark contexts

Add dark to any ancestor. AngularCSS provides dark defaults for the same semantic variables:

<section class="dark">
  <button>Continue</button>
</section>

Override variables inside the same selector to supply an application-specific dark presentation:

.dark {
  --background: #101828;
  --foreground: #f2f4f7;
  --primary: #84adff;
  --primary-foreground: #102a56;
}

Selectors, parts, and state

Use documented root selectors, semantic descendants, native state, and documented component state for customization beyond the shared variables:

.dialog > dialog {
  max-width: 48rem;
}

[ng-tabs] > menu > button[aria-selected="true"] {
  border-color: var(--primary);
}

Styling-only entries keep state in native selectors such as :checked, :disabled, and :open. Behavioral components expose authored attributes, ARIA state, and documented data-* state. Avoid selectors based on generated IDs or child positions.

Tailwind and other CSS tools

AngularCSS has no Tailwind dependency. Tailwind, Sass, CSS Modules, and other application toolchains can set the same custom properties or add rules in the public cascade layers. They do not need an AngularCSS-specific customization model.

Preserve behavior

Customization may change spacing, color, typography, borders, geometry, shadows, and motion. Keep focused elements visible, preserve keyboard focus, retain usable contrast and pointer targets, and keep visual order aligned with DOM order.

Use the component catalog to find each component’s selectors, states, custom properties, and live source.

5 - Compatibility and upgrades

AngularCSS declares @angular-wave/angular.ts with the npm latest tag and tests the registry’s current release in CI. A daily compatibility run catches a new AngularTS release even when AngularCSS source has not changed. The package lock still records the exact version used for a reproducible AngularCSS build.

Supported environments

• Current Chromium, Firefox, and WebKit engines are required browser projects.
• Node.js 24 or newer is required for development, documentation, and package builds.
• The distributed CSS and browser JavaScript are prebuilt. Consumers do not need the AngularCSS build toolchain.
• Behavioral components require AngularTS. Styling-only foundations, elements, patterns, and recipes can use the compiled stylesheet alone.

AngularCSS uses current platform features including native dialog, the Popover API, CSS custom properties, cascade layers, logical properties, :has(), and @scope. Test the final application against its own supported browser policy, content, localization, zoom, and assistive technology.

Upgrade both packages

Resolve both current releases together and review the lockfile:

npm install @angular-wave/angular.ts@latest @angular-wave/angular.css@latest
npm run build

Then run the application’s keyboard, form, overlay, narrow viewport, and data workflow tests. Review the AngularCSS changelog for selector, attribute, event, or custom-property changes. Versions below 0.1.0 may refine public contracts while the catalog is being stabilized.

Upgrading from 0.0.1 to 0.0.2

The core package no longer uses Tailwind in its source, build, or distribution. Continue importing the same compiled CSS entrypoint. Customize semantic CSS variables directly; Tailwind applications can set those variables from their own stylesheet without an AngularCSS adapter.

0.0.2 adds DTCG 2025.10 token files, density and contrast contexts, print attributes, broader enterprise-state recipes, and stricter accessible HTML. Re-test any application CSS that depended on undocumented generated selectors or Tailwind implementation variables.

Diagnose a compatibility failure

Run the same policy check used by CI:

npm install --no-save --package-lock=false @angular-wave/angular.ts@latest
npm run check:angular-ts-version -- --registry-latest
npm test

The check reports the exact installed AngularTS compatibility target before the browser suite runs.