aiskillstore/ui-style-guide

Frontend Style Guide & Coding Conventions

This document defines the coding standards, architectural patterns, and design system for the Guessimate Angular frontend.

1. Technology Stack

• Framework: Angular 20+
• Styling: Tailwind CSS 4
• State Management: Angular Signals & RxJS
• Build System: Angular CLI (Esbuild)

2. Project Structure

We follow a Feature-Based directory structure. Code is organized by domain feature rather than technical type.

src/app/
├── core/            # Global singletons (Guards, Interceptors, Global Services)
├── layout/          # Layout components (Navigation, Footer, Shell)
├── features/        # Feature modules (Domain logic)
│   ├── home/
│   ├── session/
│   │   ├── components/  # Dumb/Presentational components
│   │   ├── pages/       # Smart/Container components (Routed)
│   │   ├── services/    # Feature-specific state/logic
│   │   └── models/      # Feature-specific types
│   └── ...
├── websocket/       # WebSocket infrastructure
└── shared/          # Shared utilities (Pipes, Directives, Generic UI)

Naming Conventions

• Files: Kebab-case (e.g., session-page.component.ts, auth.service.ts).
• Classes: PascalCase (e.g., SessionPageComponent, AuthService).
• Selectors: app- prefix, kebab-case (e.g., app-user-profile).
• Signals: No suffix, descriptive noun/verb (e.g., user(), isLoading()).
• Observables: $ suffix (e.g., user$).

3. Component Standards

Definition

• Use Standalone Components (standalone: true is default in v19+).
• Prefer Inline Templates for most components to keep logic and view co-located.
• Avoid external CSS files; use Tailwind CSS utility classes directly in the template.

@Component({
    selector: 'app-example',
    imports: [CommonModule, RouterLink], // Explicit imports
    template: `
    <div class="p-4 bg-surface-100 rounded-lg">
      <h1 class="text-2xl font-bold text-gray-900">{{ title() }}</h1>
    </div>
  `
})
export class ExampleComponent {
    title = signal('Hello World');
}

Control Flow

Use the new built-in Angular Control Flow syntax.

<!-- Good -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}

Dependency Injection

Prefer the inject() function over constructor injection for better type inference and cleaner code.

// Good
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);

// Avoid if possible
constructor(private
route: ActivatedRoute
)
{
}

4. State Management

• Local State: Use signal() for primitive state.
• Shared State: Use Signal Stores (Services using Signals) provided at the appropriate level (Root or Component).
• Reactive Data: Use computed() for derived state and effect() sparingly for side effects.

@Injectable()
export class SessionStore {
    // State
    private readonly _state = signal<SessionState>(initialState);

    // Selectors
    readonly lobby = computed(() => this._state().lobby);
    readonly connection = computed(() => this._state().connection);

    // Actions
    setLobby(lobby: Lobby) {
        this._state.update(s => ({...s, lobby}));
    }
}

5. Styling & Design System

We use Tailwind CSS 4 with a semantic color palette defined in styles.css.

Usage Rules

1. Utility-First: Write classes directly in HTML.
2. No Magic Numbers: Use theme values (e.g., p-4 not p-[16px]).
3. Dark Mode: Use the dark: modifier for all color-related classes.

Color Palette

The application uses a semantic naming convention mapped to Tailwind colors.

Core Colors

| Category | Semantic Name | Light Mode | Dark Mode | Usage | |:------------------|:----------------|:--------------|:-----------------|:-------------------------------------| | Background | background | gray-50 | gray-950 | Main application background | | Surface | surface | white | gray-900 | Cards, modals, sections | | Surface Alt | surface-alt | gray-100 | gray-800 | Secondary backgrounds, input fields | | Primary | brand | blue-600 | blue-600 | Primary actions, buttons, highlights | | Primary Muted | brand-muted | blue-50 | blue-900/30 | Selected states, light highlights | | Success | success | emerald-500 | emerald-600 | Success states, confirmation | | Success Muted | success-muted | emerald-50 | emerald-900/30 | Success backgrounds | | Danger | danger | red-600 | red-600 | Errors, destructive actions | | Danger Muted | danger-muted | red-50 | red-900/30 | Error backgrounds | | Warning | warning | amber-500 | amber-600 | Warnings, pending states | | Warning Muted | warning-muted | amber-50 | amber-900/30 | Warning backgrounds |

Typography & Borders

| Category | Light Mode | Dark Mode | Usage | |:--------------|:-----------|:-----------|:-----------------------------------| | Primary | gray-900 | white | Main headings and body text | | Secondary | gray-500 | gray-400 | Subtitles, labels, secondary info | | Muted | gray-400 | gray-500 | Disabled text, placeholders | | Border | gray-200 | gray-800 | Standard dividers and card borders |

Implementation in styles.css

Colors are defined using CSS variables in the @theme block:

@theme {
    --color-brand-600: var(--color-blue-600);
    --color-surface-100: var(--color-stone-100);
    /* ... */
}

6. Common Component Patterns

Cards & Containers

Standard styling for content containers (like estimation cards, lists):

<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
    <!-- Content -->
</div>

• Background: bg-surface-100/60 (Light) / dark:bg-gray-900/40 (Dark)
• Border: border border-surface-200 (Light) / dark:border-gray-800/60 (Dark)
• Rounding: rounded-md (Standard)
• Dividers: divide-y divide-surface-300 dark:divide-gray-800

Typography Headers

<div class="flex flex-col gap-1">
    <h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">Title</h2>
    <span class="text-sm font-normal text-gray-600 dark:text-gray-400">Subtitle description</span>
</div>