Anarchitecture Bricks Docs

Repository documentation hub for packages, guides, and generated references.

Design/UI Systems Guide

Intent

This guide defines the cross-stack design and UI system model for Anarchitecture Bricks. It explains how to consume @anarchitects/* packages so design contracts, composition APIs, and runtime layouts stay consistent across domains and applications.

Contract ownership for DTOs and domain models is defined in the canonical TS Contracts Guide.

System Layers

The UI system is layered and should be adopted in order:

  1. @anarchitects/common-angular-design
  2. @anarchitects/common-angular-ui-composition
  3. @anarchitects/common-angular-ui-primitives
  4. @anarchitects/common-angular-ui-layouts
  5. Domain UI slices (@anarchitects/forms-angular/ui, @anarchitects/auth-angular/ui)

Domain orchestration should still follow Angular layering: ui <- feature -> state -> data-access.

Backend support should still follow Nest layering: presentation -> application <- infrastructure.

Token and Theme Model

Use token and theme contracts from @anarchitects/common-angular-design as the primary extension mechanism:

Example:

.anx-root[data-anx-theme='brand-a'] {
  --anx-sys-color-primary: #0f766e;
  --anx-sys-color-accent: #0ea5e9;
  --anx-layout-content-max-width: 72rem;
}

Shell/Layout Contract Hardening (Phase 2)

Shell and layout contracts are intentionally separated to prevent collisions.

Source-of-truth symbols:

Package author rule source:

Enforcement source:

Package Author CSS Class Rules

When building UI package components, understand the two categories of semantic classes.

Shell Utility Classes (Consumer Use Only)

These classes control layout and spacing in consumer app shells and must not be applied to package component host elements:

Critical Rule: Applying these to package component hosts causes unintended double-spacing when the component is nested inside a consumer's layout container using the same utilities.

Design Hook Classes (Component-Safe)

These classes define visual treatment safe for component styling:

Correct Package Component Spacing

Use :host CSS for component-internal spacing instead:

@Component({
  selector: 'anarchitects-ui-card',
  host: {
    class: 'anx-card anx-surface', // Design hooks OK; no shell utilities
    '[class.anx-card--interactive]': 'interactive()',
  },
  styles: `
    :host {
      padding: var(--anx-layout-block-padding-current);
      gap: var(--anx-layout-gap-stack);
    }
  `,
})
export class AnarchitectsCard {}

For details, see the CSS Class Rules in the contracts documentation.

Single-Source Theme Setup

Use one canonical app-bootstrap path for shared design context:

  1. Apply base styles once before rendering.
  2. Register provideDesignSystemConfig(...) at app root.
  3. Avoid manual data-anx-theme, data-anx-density, and data-anx-surface on the root in new setups.

Example:

import { bootstrapApplication } from '@angular/platform-browser';
import { provideDesignSystemConfig } from '@anarchitects/common-angular-design/config';
import { applyAnxBaseStyles } from '@anarchitects/common-angular-design/styles';

applyAnxBaseStyles();

bootstrapApplication(AppComponent, {
  providers: [
    ...provideDesignSystemConfig({
      theme: 'default',
      density: 'comfortable',
      surface: 'plain',
      layout: 'list',
      columns: 1,
    }),
  ],
});

The provider applies anx-root, data-anx-theme, data-anx-density, and data-anx-surface on document.documentElement during bootstrap.

data-anx-layout and data-anx-columns remain explicit where local layout scope is required.

Precedence Rules

For managed root values (theme, density, surface) the resolution order is:

  1. Directive input (designTheme, designDensity, designSurface)
  2. Explicit host/root attribute value (data-anx-*)
  3. Provider configuration (provideDesignSystemConfig)

This keeps migration safe because existing explicit attributes remain authoritative.

Migration and Validation Workflow

When migrating existing consumers to hardened shell/layout contracts:

  1. Keep shell utility classes only in consumer shell wrappers.
  2. Remove shell utility classes from shared package component hosts and internal templates.
  3. Move component spacing to explicit component CSS (:host, component-scoped selectors).
  4. Validate contract enforcement and downstream behavior:
    • yarn nx run guardrails:test
    • yarn nx run forms-angular-ui:test --testFile=libs/forms/angular/ui/src/form.spec.ts
  5. Run docs verification:
    • yarn nx run docs-hub:validate-content
    • yarn nx run docs-hub:build
    • yarn nx run docs-hub:verify

For full migration sequence examples, see the Theme Migration Guide.

Composition Contracts

Use @anarchitects/common-angular-ui-composition for stable projection contracts:

Example:

<anarchitects-ui-card>
  <h3 anxSlot="header">Summary</h3>
  <p anxSlot="content">Rendered with stable slot contracts.</p>
  <div anxSlot="footer">
    <button anxSlot="actions">Continue</button>
  </div>
</anarchitects-ui-card>

Primitive Contracts

Use @anarchitects/common-angular-ui-primitives for reusable, non-domain visual building blocks:

Layout Runtime Contracts

Use @anarchitects/common-angular-ui-layouts when runtime layout selection is required:

Domain Integration Matrix

Domain Package Role Design/UI System Integration
@anarchitects/forms-angular Dynamic form/list/detail flows Consumes shared composition, primitives, and layout runtime contracts
@anarchitects/auth-angular Auth feature orchestration and domain UI Uses shared design tokens/primitives and contract-safe state composition
@anarchitects/forms-nest Forms API/service backend Must preserve contract stability used by frontend layouts and form rendering
@anarchitects/auth-nest Auth lifecycle backend Must preserve contract stability used by frontend state/feature and policy flows

Cookbook Patterns

Anti-Patterns

Adoption Checklist