| version | 10.0.1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| name | Alauda UI | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| description | A design specification for dense enterprise console interfaces using Alauda UI tokens and SCSS theme tools. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| metadata |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| colors |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| typography |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rounded |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| spacing |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| components |
|
This document defines the design system behind Alauda UI. It is written for coding agents that need to produce styles matching Alauda's product design language. Follow the Google design.md structure first; Alauda-specific SCSS guidance is included only where it helps implement the spec correctly.
Alauda UI is a dense enterprise console design system. Its screens are used for operational workflows: data comparison, status monitoring, resource management, form entry, and fast corrective actions. The visual tone is calm, precise, and utilitarian.
The system optimizes for clarity, density, and consistency. It should not look like a marketing site, portfolio, or editorial page. Avoid large decorative hero sections, gradient-heavy backgrounds, oversized ornamental type, arbitrary accent colors, and card grids that do not serve a workflow.
When creating interface styles, start with the product task: what state must be scanned, what action must be taken, and what feedback must be visible. Use the tokens in this file to express hierarchy, density, state, and surface relationships.
Use colors semantically. Do not choose a token because the raw color looks close; choose it because it expresses the intended role.
Primary blue is for interaction and brand emphasis: primary actions, active indicators, selected states, focus affordances, and links. Stronger or weaker primary steps are used only for interaction states such as hover, active, selected backgrounds, and disabled primary controls.
Status colors communicate system state:
- Success uses
successand its steps. - Warning uses
warningand its steps. - Error, danger, destructive actions, and failed states use
dangerand its steps. - Informational active state can use
primarywhen the component has no separate info palette.
Neutral colors define information hierarchy:
text-main,text-secondary,text-help,text-disabled, andtext-placeholderare preferred for text roles.surface-page,surface-button,surface-raised, andsurface-popperdefine background roles.border-defaultanddividerseparate information without heavy visual weight.shadow-originis an input to shadow formulas, not a visible text or icon color.
Alauda CSS color variables store RGB triplets, not complete CSS colors. In SCSS, prefer theme helpers. In raw CSS, wrap the variable.
@use '@alauda/ui/theme/var' as var;
.summary {
color: var.use-text-color(main);
background-color: var.use-rgb(n-10);
border: 1px solid var.use-rgb(border);
}
.raw-css-example {
color: rgb(var(--aui-color-main-text));
}Never write color: var(--aui-color-primary). Never introduce missing palette steps.
Alauda UI typography is compact and task-oriented. body-medium is the default product text style: 14px text on a 20px line. Use larger type only for real hierarchy, such as page titles, section titles, or tab headers.
Use the SCSS text mixin when writing custom styles. It keeps font size, line height, weight, and text color aligned with the design tokens.
@use '@alauda/ui/theme/mixin' as mixin;
.section-title {
@include mixin.text-set(l, main, bolder);
}
.help-text {
@include mixin.text-set(s, help);
}Do not scale font sizes with viewport width. Do not use display-scale typography inside compact panels, table cells, form rows, or operational toolbars.
Layout should support scanning and repeated action. A typical enterprise console screen contains a title or context header, a toolbar or filter area, a primary data/form surface, and contextual feedback. Surfaces should be quiet; the data and state should carry the page.
Use spacing tokens to create rhythm. The base working gap is 8px. Use 12px and 16px for section spacing, 20px and above for larger separation. Avoid arbitrary values such as 6px, 10px, 14px, 18px, or 30px unless an existing component requires them.
Control density follows a fixed height scale:
- Mini: 24px for compact embedded controls.
- Small: 28px for dense toolbars and table-adjacent controls.
- Medium: 32px for normal working density.
- Large: 40px for intentionally spacious forms.
Use page and raised surfaces semantically. surface-page is the default background. surface-raised is for framed content. Borders and dividers should be subtle and structural, not decorative.
Elevation represents hierarchy, overlay position, or focus. It is not decoration. Use the existing shadow mixins and pattern mixins rather than custom shadow formulas.
@use '@alauda/ui/theme/var' as var;
@use '@alauda/ui/theme/mixin' as mixin;
@use '@alauda/ui/theme/pattern' as pattern;
.raised-surface {
@include pattern.shadow-2;
}
.floating-panel {
background-color: var.use-rgb(popper-bg);
@include mixin.popper-shadow;
}
.modal-panel {
@include mixin.modal-shadow;
}Focus rings are part of depth. Use outline-shadow(...); it adapts opacity for light and dark themes.
@use '@alauda/ui/theme/mixin' as mixin;
.custom-control.isFocused {
@include mixin.outline-shadow(primary);
}Do not use large blurred shadows, glow effects, or colored decorative shadows.
Shapes are restrained. Most controls use the small 2px radius. Larger framed surfaces use 4px. Circular controls and pills should derive from the component height or use a full radius.
Use shape to clarify affordance, not to decorate. Do not introduce large rounded cards or soft pill containers unless the existing component pattern requires them.
Component tokens in the front matter describe style roles, not an exhaustive API catalog. Use them as examples of how primitives compose into controls, input states, text roles, surfaces, and status feedback.
For SCSS, use Alauda's theme tools:
@use '@alauda/ui/theme/var' as var;
@use '@alauda/ui/theme/mixin' as mixin;
@use '@alauda/ui/theme/pattern' as pattern;Core helpers:
var.use-var(name)returnsvar(--aui-<name>).var.use-rgb(name)returnsrgb(var(--aui-color-<name>)).var.use-rgb(name, level)returns a palette step, for examplevar.use-rgb(primary, 6).var.use-rgba(name, opacity)returnsrgba(var(--aui-color-<name>), <opacity>).var.use-text-color(level)returns semantic text roles such asmain,secondary,help,disabled, orplaceholder.mixin.text-set(size, color, weight)applies compact typography.mixin.icon-set(size, color)aligns icons to text rhythm.mixin.theme-lightandmixin.theme-darkscope theme-aware overrides.mixin.card-shadow,mixin.popper-shadow,mixin.modal-shadow, andmixin.modal-backdropencode surface depth.mixin.transition(target)andmixin.scroll-barkeep motion and scrollbars consistent.pattern.shadow-0,pattern.shadow-2,pattern.shadow-8, andpattern.shadow-16define raised surfaces.
Angular style-related inputs should map to design semantics. size usually means large, medium, small, or mini; use medium as the default product density. Inputs such as type, status, plain, solid, disabled, readonly, loading, checked, and active should express action hierarchy, feedback state, density, or interaction state. Prefer the style input over custom overrides when it exists.
Custom SCSS should compose layout around components or implement product-specific surfaces while still using these tokens and helpers.
Do:
- Use the canonical token groups in this file when choosing color, type, spacing, radius, and component roles.
- Treat color as semantic state and hierarchy.
- Keep pages data-first, compact, and task-oriented.
- Use
@use '@alauda/ui/theme/var' as var,mixin, andpatternfor custom SCSS. - Use
rgb(...)/rgba(...)wrappers or Sass helpers for--aui-color-*variables. - Use theme scopes instead of hard-coded dark-mode colors.
- Keep hover, active, focus, disabled, error, and loading states visible and dimensionally stable.
Don't:
- Do not simplify this document by removing Google-required token groups or canonical sections.
- Do not use raw hex colors for themeable UI.
- Do not use
var(--aui-color-*)as a complete CSS color. - Do not invent palette steps or unrelated accent colors.
- Do not inflate spacing or typography for decorative effect.
- Do not create one-off shadows, focus rings, scrollbars, or dark-mode overrides when theme mixins exist.
- Do not compensate for the wrong Angular style input with raw CSS overrides.