@geoit/ui

GEO design system for Angular 18 + ng-zorro 18. Standalone components, design tokens, and AI-ready usage docs.

Install

npm install @geoit/ui

Peer dependencies (install in your app if missing):

npm install @angular/animations@^18 @angular/common@^18 @angular/core@^18 \
  @angular/forms@^18 @angular/cdk@^18 @ant-design/icons-angular@^18 ng-zorro-antd@^18

Setup styles (once per app)

In your global styles (e.g. styles.scss):

@import 'node_modules/@geoit/ui/src/lib/styles/design-tokens.scss';
@import 'node_modules/@geoit/ui/src/lib/styles/theme.scss';

Use tokens in your CSS — do not hardcode brand colors or radius:

• var(--geo-color-primary-default)
• var(--geo-radius) (default 6px)

Quick start

import { Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
  GeoButtonComponent,
  GeoInputComponent,
  GeoFormModalComponent,
  GeoToastService,
} from '@geoit/ui';

@Component({
  standalone: true,
  imports: [FormsModule, GeoButtonComponent, GeoInputComponent, GeoFormModalComponent],
  template: `
    <geo-button appearance="primary" color="brand" icon="plus" (clicked)="open = true">
      Thêm mới
    </geo-button>

    <geo-form-modal
      [open]="open"
      title="Thêm mới"
      cancelText="Hủy bỏ"
      okText="Lưu"
      (openChange)="open = $event"
      (ok)="save()"
    >
      <geo-input label="Tên" [required]="true" [block]="true" [(ngModel)]="name"></geo-input>
    </geo-form-modal>
  `,
})
export class DemoComponent {
  open = false;
  name = '';

  constructor(private toast: GeoToastService) {}

  save(): void {
    this.toast.success('Thành công!', 'Đã lưu.');
    this.open = false;
  }
}

Common components

| Need | Component | Example | |------|-----------|---------| | Button / CTA | geo-button | <geo-button appearance="primary" color="brand">Lưu</geo-button> | | Text field | geo-input | <geo-input label="Họ tên" [(ngModel)]="name" [block]="true"> | | Select | geo-select | <geo-select [options]="opts" [(ngModel)]="v" [block]="true"> | | Checkbox | geo-checkbox | <geo-checkbox label="Đồng ý" [(checked)]="ok"> | | Radio | geo-radio | <geo-radio [options]="opts" [(ngModel)]="v"> | | Form dialog | geo-form-modal | See Quick start | | Confirm delete | geo-confirm-modal | [visible] + (confirm) | | Steps in dialog | geo-form-modal + geo-stepper | See recipes | | Page title | geo-page-title | <geo-page-title title="Chi tiết hồ sơ"> | | Breadcrumb | geo-breadcrumb | [items]="[{ label, link? }]" | | Toast | GeoToastService | this.toast.success(title, message) | | Alert | geo-alert | type="success" \| "error" \| … | | Status pill | geo-status-tag | status="success" label="Đã duyệt" | | Table | geo-table | [columns] + [data] + paging | | Upload | geo-upload | Drag-drop multi-file | | Typography | geo-typography | variant="h3" \| "body" \| … |

Button API (quick)

| Input | Values | Default | |-------|--------|---------| | appearance | primary | secondary | tertiary | primary | | color | brand | danger | warning | success | brand | | icon / iconPlacement | Ant icon name; start | end | start | | disabled / iconOnly / active | boolean | false |

<geo-button appearance="primary" color="brand" icon="plus">Thêm mới</geo-button>
<geo-button appearance="primary" icon="right" iconPlacement="end">Tiếp theo</geo-button>
<geo-button appearance="secondary" (clicked)="cancel()">Hủy</geo-button>

Form controls & ngModel

These implement ControlValueAccessor — use [(ngModel)] or reactive forms:

geo-input, geo-textarea, geo-select, geo-radio, geo-date-picker, geo-date-range-picker, geo-slider

geo-checkbox uses [(checked)] (not CVA).

Toast (preferred)

import { GeoToastService } from '@geoit/ui';

constructor(private toast: GeoToastService) {}

this.toast.success('Thành công!', 'Đã lưu hồ sơ.');
this.toast.error('Lỗi!', 'Không thể lưu.');

Full docs (shipped in the package)

After install:

| Path | Purpose | |------|---------| | node_modules/@geoit/ui/ai/AGENTS.md | Rules for humans & AI agents | | node_modules/@geoit/ui/ai/README.md | Component index | | node_modules/@geoit/ui/ai/catalog.json | Machine-readable catalog | | node_modules/@geoit/ui/ai/components/*.md | Per-component API (inputs/outputs/examples) | | node_modules/@geoit/ui/ai/recipes.md | Copy-paste screen patterns |

Open a component doc before using it, e.g.:

node_modules/@geoit/ui/ai/components/geo-button.md
node_modules/@geoit/ui/ai/components/geo-form-modal.md
node_modules/@geoit/ui/ai/components/geo-table.md

Cursor rule (recommended)

.cursor/rules/geo-ui.mdc in your app:

---
description: Use @geoit/ui components
alwaysApply: true
---

UI must use `@geoit/ui`. Before writing UI, read:
- node_modules/@geoit/ui/ai/AGENTS.md
- node_modules/@geoit/ui/ai/catalog.json
- node_modules/@geoit/ui/ai/components/<selector>.md when needed

Design tokens

| Group | Examples | |-------|----------| | Primary | --geo-color-primary-default (#9A4828), hover, light, dark, background | | Neutral | --geo-color-neutral-900 … 100, white | | Semantic | success / error / warning / info | | Radius | --geo-radius (6px) | | Font | --geo-font-family |

TypeScript mirror: geoColorTokens from @geoit/ui (via styles/tokens export).

License

Internal / project license — see repository.