Avatars

Load when: rendering a profile image, initials fallback, avatar size or accessible identity label.

Also read: Shared component guidelines.

Do not load for: generic icons or identity authorization policy.

BEM identity: crm-avatar and crm-initials-avatar are targets; size props map to --size-. No target block is currently emitted in rendered HTML.

Use Avatar, AvatarImage, and AvatarFallback from @/components/ui/avatar when an image can load progressively. Avatar sizes are sm, default, and lg; group utilities are also available.

Use InitialsAvatar from @/shared/ui/primitives/initials-avatar when no image is available and a deterministic text-derived color is useful. Its size is sm, md, or lg; it assigns role="img" and labels the result with the supplied name.

Image alt must identify the person when the image conveys identity. Do not use initials alone as reliable identity proof; the domain must supply the canonical display name and access policy.

Source: apps/frontend/src/components/ui/avatar.tsx and apps/frontend/src/shared/ui/primitives/initials-avatar.tsx.

Badge

Load when: presenting compact status or metadata and choosing a semantic/tinted Badge variant.

Also read: Shared component guidelines and Tokens for semantic roles.

Do not load for: actionable buttons or full feedback/error states.

BEM identity: crm-badge is the target block; real variant values map to crm-badge--variant-. The block and modifiers are not currently emitted in rendered HTML.

Import Badge from @/components/ui/badge. Use for compact metadata or status, not as the only communication of a consequential state. The verified hook is data-slot="badge".

variant defaults to default. Use lightprimary, lightsecondary, lightsuccess, lightwarning, lighterror, or lightinfo for low-emphasis semantic status; use outline for neutral metadata. default, secondary, destructive, ghost, and link follow their matching semantic roles.

Badges keep one line and clip overflow. Make the text self-explanatory; an icon alone is insufficient for a status. The component can render another semantic tag through its Base UI render prop, but do not turn a non-actionable status into a button merely for styling.

Source: apps/frontend/src/components/ui/badge.tsx.

Button

Load when: implementing an action, choosing Button variant/size/loading or reviewing icon-only accessibility.

Also read: Shared component guidelines and Design guidelines for action hierarchy.

Do not load for: route navigation that belongs to a link.

BEM identity: crm-button is emitted by the shared root. Real variant values map to crm-button--variant- and loading={true} maps to crm-button--loading; size modifiers and crm-button__icon remain unassigned. The Deal Sheet browser check verified the base block.

Import Button from @/components/ui/button. Use it for an action; use a link component for navigation.

<Button type="button" loading={isSaving} onClick={save}>Lưu</Button>

Focus-visible and invalid states use the semantic ring/destructive roles. Disabled controls are non-interactive and dimmed. The component does not show a spinner, perform confirmation, or persist data.

Source: apps/frontend/src/components/ui/button.tsx.

Cards

Load when: grouping related information/actions in a Card or using the dashboard summary-card composition.

Also read: Shared component guidelines and the owning layout/pattern.

Do not load for: page grid/shell structure or automatically clickable containers.

BEM identity: crm-card is emitted on the shared root and verified in the Deal Sheet. Card elements and size modifiers remain unassigned until their owners emit them.

Import the Card family from @/components/ui/card. Use it to group related information or actions; do not use it as a substitute for page layout.

The root uses data-slot="card"; subparts use corresponding data-slot values. Card radius, surface, text, and border derive from semantic tokens. A card is not automatically clickable: wrap the whole card in a route link only when the whole summary navigates, as StatCard does.

Source: apps/frontend/src/components/ui/card.tsx and apps/frontend/src/modules/dashboard/components/stat-card.tsx.

Checkbox

Load when: a form needs a binary, labelled choice.

Import Checkbox from @/components/ui/checkbox. Its rendered root emits crm-checkbox; the caller owns the associated label, validation and persisted value. It does not replace a domain-specific multi-state control.

Evidence: apps/frontend/src/components/ui/checkbox.tsx and Deal commerce composition.

Shared component guidelines

Load when: creating, extending or reviewing a reusable component or deciding whether feature UI belongs in a shared owner.

Also read: the named component contract, Naming and DOM identity when identity/aliases/variants change, applicable design guidelines, tokens, and governance for ownership gaps.

Owner and use decision

1. Reuse the existing component unchanged when its behavior fits.

2. Extend its shared owner when the difference is a compatible reusable prop/state; check existing consumers and defaults.

3. Compose a feature adapter when only copy, data, permissions, validation or persistence differ.

4. Create a new shared owner only for a concrete recurring behavior that existing owners cannot reasonably represent; document the comparison.

Required component contract

Each reusable owner documents its canonical name/aliases, import, BEM block/stable elements/real modifier mappings and adoption status, use/avoid, anatomy, variants/sizes, key props/defaults/events, token/style rules, applicable states, keyboard/focus/announcement behavior, responsive/overflow behavior, ownership boundaries, minimal usage and source/demo/test evidence.

Describe the delta for applicable default, hover, focus, active/selected, disabled, read-only, loading, empty, error and success states. Do not list unsupported states or confuse disabled with read-only.

Implementation rules

Validation

Use source inspection, focused tests and rendered product output for public API/state changes and BEM, focus, layout, wrapping or responsive claims. The generated portal documents the contract but does not prove runtime geometry or screen-reader output. Follow Validation; unit tests alone do not prove those conditions.

Deal form

Load when: creating or reviewing /deals create/edit Sheet.

DealFormSheet owns Sheet presentation and selects the approved xlarge drawer target; its current 90vw implementation matches the preferred ratio but does not yet use a typed size API. DealForm owns React Hook Form state and Deal business orchestration; DealFormSection composes Card and FormSectionHeading; DealLeadPicker owns only Deal-specific Lead presentation/query mapping. The form emits crm-deal-form; sections emit crm-deal-form-section and the supporting owners use their respective blocks.

Pipeline remains first. Customer/details and commerce/billing retain the existing desktop 60/40 grid and mobile stacking. Pricing, payment locks, association loading, nested drawers, validation and persistence remain domain behavior and are not owned by shared UI.

For an existing Deal, the Sheet must receive the full Deal detail contract so saved Lead, Account, buyer and associated Contact names render without identifier fallbacks. An ADMIN may edit Pipeline/Stage, Lead-derived customer context, products, order discount and billing only while the Deal is OPEN and not PAID. Other states keep those controls disabled and show the resume, reopen, role or payment reason. A changed Stage is submitted together with its Pipeline; changing Pipeline clears an invalid Stage. The current inactive Pipeline remains visible for history but is not a selectable target after moving away.

Lead replacement reuses the create picker and association drawers. The selected buyer is the primary Contact and remains included in the associated Contact IDs. A legacy Deal without a saved billing snapshot hydrates invoice fields from the current authorized Contact/Account details, with its reusable invoice profile taking precedence and Lead identity as fallback. An existing billing snapshot remains authoritative and unchanged; manual billing edits survive customer refreshes. Legacy amount-only Deals require an explicit commerce-adoption action and never receive a synthesized Product. Request-affecting edits on a PENDING or price-confirmed Deal expose the explicit supersede acknowledgement; the informational discount code alone does not alter pricing or supersede a payment request. Cancel and nested-drawer interaction retain draft-only behavior until the single update request succeeds.

New commerce Deals and explicit legacy commerce adoption require payment-ready invoice identity before submit: legal name and address for every recipient, company tax code for companies, delivery email when delivery is enabled, and both personal identity fields when either is supplied. An explicit billing edit on an existing commerce Deal must also satisfy that contract. Unrelated edits preserve incomplete historical billing snapshots rather than forcing migration. DealBillingFields renders the applicable native required semantics and inline validation through the existing Deal form owner.

Evidence: Deal component tests, particularly deal-form-commerce.test.tsx and deal-customer-links.test.tsx.

Deal invoice status

Load when: displaying or changing invoice issuance state for a Deal.

DealInvoiceStatusBadge presents NOT_REQUESTED, PENDING, ISSUED, and VOIDED independently from pipeline stage and payment status. DealInvoiceStatusPanel emits crm-deal-invoice-status, composes the shared Badge, Select, and Button owners, and persists through the dedicated Deal invoice-status command.

The UI does not offer ISSUED before full payment. The backend remains authoritative and rejects issuance unless paymentStatus is PAID. An issued invoice can only move to VOIDED; voided invoices can be queued or reissued. Existing Deals default to NOT_REQUESTED.

Evidence: deal-invoice-status.test.tsx and backend deal-invoice-status.test.ts.

Deal payment

Load when: creating or reviewing the payment area in Deal detail.

DealPaymentPanel owns payment-state queries, QR request presentation, receipt history and role-based actions. It emits crm-deal-payment-panel; disabled state emits crm-deal-payment-panel--disabled, and the server-authorized ADMIN selector emits crm-deal-payment-panel__account-selector. The selector displays only masked labels supplied by the server, defaults to the configured account and locks to an existing immutable request. Non-Admins never receive or render the alternate-account catalog.

When SePay is disabled, the panel hides selector/create/copy/download/open-QR actions and stored actionable instructions while retaining request history, receipt history and eligible audited manual confirmation. DealPaymentManualConfirmationDialog is the bounded domain confirmation owner and emits crm-deal-payment-manual-confirmation; it composes the shared Dialog, FormRow, Input, Textarea and Button owners.

Manual confirmation is available only before payment on an eligible commerce Deal. The dialog requires the exact current VND total; confirmation note, bank transaction ID, and actual transfer content are optional evidence. Submission remains pending-safe and dismissible before submit. Backend permissions, row locking, Payment Receipt creation, actor audit, confirmation time and settlement are domain behavior rather than shared UI concerns.

Evidence: deal-payment-panel.test.tsx and manual-payment-confirmation.test.ts.

DetailEditableField

Load when: rendering a labeled value that swaps to a caller-owned editor in an entity detail panel.

Import DetailEditableField from @/components/ui/detail-editable-field. It owns the 38% label/value layout and composes InlineEditableValue; callers retain editor controls, permissions, autosave, validation, and persistence.

BEM identity: crm-detail-editable-field; __label and __value are its stable anatomy. Source verification only.

AccountDetailEditableField remains a compatibility alias. New Lead and Contact callers must import the shared owner directly.

Entity references

Load when: implementing a picker or read/edit/clear association field while keeping detail navigation distinct.

Also read: Editable association, Shared component guidelines and the domain form policy.

Do not load for: deleting the referenced entity or selecting a simple enum.

BEM identity: crm-entity-picker is emitted and verified in source; crm-entity-reference-field and crm-inline-editable-value remain targets. Applicable owner states map to --loading, --error, --editing and --disabled; stable elements remain unassigned until an authorized audit identifies owned anatomy.

Use these owners for an association UI while retaining domain query, authorization, creation, and save behavior in the caller.

EntityReferenceField exposes loading, error, edit, open-detail, and clear affordances. It blocks edits while disabled or loading; when a value can open detail, navigation is separate from the edit affordance. InlineEditableValue focuses the first editor control, handles Escape, and only commits Enter for its scalar default (commitOnEnter=true).

Use a specific editLabel and clearLabel for icon-only controls. Preserve unsaved draft state when an association opens a nested detail UI.

Working-tree extension under validation

The current uncommitted EntityPicker source can render an Xóa chọn action when allowClear, a selected label and onClear are present. It handles click, Enter and Space without opening the picker. This extension has not been accepted as a stable shared contract or verified with a focused rendered test in this initialization; inspect the pending source/test state before relying on disabled/loading or nested-trigger behavior.

Source: apps/frontend/src/components/ui/entity-picker.tsx, apps/frontend/src/components/ui/entity-reference-field.tsx, and apps/frontend/src/components/ui/inline-editable-value.tsx.

Feedback and status

Load when: choosing progress, skeleton, private-field, toast, loading, empty, error or success presentation.

Also read: Shared component guidelines and the owning form/pattern for persistent recovery.

Do not load for: semantic status labels that only need a Badge.

BEM identity: crm-progress, crm-skeleton, crm-private-field and crm-toaster are target blocks. Stable element/modifier mappings remain unassigned until their shared owners are adopted and rendered output is inspected; no target block is currently emitted.

Use a real empty state when no data exists, an error state when a request fails, and a disabled/loading action guard while an operation is pending. Toasts are supplemental feedback; do not rely on them as the only indication that a form field failed validation or a destructive operation completed.

Source: apps/frontend/src/components/ui/progress.tsx, apps/frontend/src/components/ui/skeleton.tsx, apps/frontend/src/components/ui/private-field.tsx, apps/frontend/src/components/ui/sonner.tsx, and apps/frontend/src/app/providers/app-providers.tsx.

Form row

Load when: laying out a label, control, helper and error or choosing responsive/top/left field alignment.

Also read: Inputs and selection, Shared component guidelines and the owning form pattern.

Do not load for: unlabeled decorative content or form submission logic.

BEM identity: crm-form-row is emitted; __label and __control map to owned anatomy. __help, __error and layout modifiers remain unassigned until an owner emits them. Source verification covers the adopted classes.

Import FormRow from @/components/ui/form-row for a labeled control or a small grouped control set. It does not own form submission or validation.

Use the render-function child for exactly one associated control so id, aria-describedby, aria-invalid, and aria-required reach it:

<FormRow label="Tên" required error={errors.name}>
  {(control) => <Input {...control} value={name} onChange={onChange} />}
</FormRow>

For grouped controls, use normal children; the group receives the label association. Current root hook: data-slot="form-row".

Source: apps/frontend/src/components/ui/form-row.tsx.

FormSectionHeading

Load when: composing a repeated titled form group.

Import FormSectionHeading from @/components/ui/form-section-heading. It renders an h3 divider with the crm-form-section-heading block. Use it inside a feature adapter or Card; it owns no data, validation, save action, or responsive layout.

Evidence: source apps/frontend/src/components/ui/form-section-heading.tsx; Deal adapter deal-form-sections.tsx.

Components

Use this index when selecting, creating or changing reusable UI. Read Shared component guidelines, then load only the named component contract. For identity changes, also read Naming and DOM identity.

Actions

Inputs and associations

Containment and navigation

Data display and feedback

Inventory requiring source inspection

Naming and DOM identity

The selected block targets and their non-adopted status are governed by Naming and DOM identity. Do not infer stable elements or modifiers from target names; the named component concept and rendered evidence must establish those mappings.

Shared ownership

Shared UI owners render presentation and local interaction. Feature modules own queries, permissions, API calls, persistence, confirmation requirements, and route effects. The global rule and required states live in Shared component guidelines.

Inputs and selection

Load when: choosing Input, Textarea, Select or SearchableSelect and defining label, invalid, disabled or filtering behavior.

Also read: Form row, Shared component guidelines and the domain validation policy.

Do not load for: remote entity search/creation that belongs to EntityPicker.

BEM identity: crm-input, crm-textarea and crm-searchable-select are emitted and verified in source. crm-select remains a target. Owned Select/SearchableSelect parts may become BEM elements; invalid, disabled or open modifiers must map to their real native/ARIA/prop states.

Use the owner that matches the interaction; the feature owns value state, validation schema, loading, and persistence.

Always provide a visible label through FormRow or an equivalent label. Placeholder text is not a label. Use disabled when the user cannot interact; use read-only display when the value needs to remain available. SearchableSelect accepts already loaded options only and does not own remote search, permissions, or saving.

Source: apps/frontend/src/components/ui/input.tsx, apps/frontend/src/components/ui/textarea.tsx, apps/frontend/src/components/ui/select.tsx, and apps/frontend/src/shared/ui/primitives/searchable-select.tsx.

Lead forms and detail adapters

Load when: changing a Lead create Sheet, inline detail edit panel, or read-only detail surface.

LeadFormSheet owns the create/edit Sheet and LeadForm owns its form anatomy. LeadFormRow remains a Lead-local adapter root, while its fixed 160px label/control layout and alignTop behavior are emitted by shared FormRow. LeadDetailEditRow similarly retains its 38% detail-panel grid. Both forms use the shared semantic FormSectionHeading.

LeadDetailSection is the reusable Lead-domain section boundary for read-only, edit metadata, and feed history. LeadDetailKeyValueRow is its named read-only value row. These remain module adapters: Lead queries, permissions, autosave, triage, drawer stack, and persistence are not shared UI responsibilities.

ConditionalFormattingPopover owns the Lead-grid conditional-format editor. ColorPicker and RuleRow are private anatomy beneath it; its fixed palette is documented in Tokens and themes. Stored legacy hexadecimal rules remain renderable, while newly created rules use the documented palette variables.

DOM identity

The named Lead adapter roots map to the rendered form, section, and value anatomy. LeadFormRow wraps the shared FormRow root, which emits the fixed label/control elements. /leads browser review verified rendered LeadFormSheet, LeadForm, LeadFormRow, and shared section-heading roots without submitting data. The detail and conditional-formatting adapters remain source-verified until those states are opened in a browser review.

Evidence: Lead form and detail-panel focused tests, plus the owning component files in apps/frontend/src/modules/leads/components/.

Popover

Load when: an anchored transient surface is needed without a route-level Sheet or Dialog.

Import the Popover composition from @/components/ui/popover. PopoverContent emits crm-popover; triggers and content retain their Base UI semantics. Domain code owns loaded content, authorization and persistence.

Evidence: apps/frontend/src/components/ui/popover.tsx.

SearchableSelect

Load when: a loaded, in-memory option set needs text filtering and keyboard selection.

Import from @/shared/ui/primitives/searchable-select. Canonical props are options, value, onChange, and placeholder; it accepts FormRow association props, plus disabled, loading, clearable, and error. Its root emits crm-searchable-select; Input remains an independent crm-input block. Caller owns remote loading, authorization, options and persistence.

Use with FormRow render props. Do not use it for remote entity search; use EntityPicker. Evidence: shared source and Deal fields/items tests.

Sheets and dialogs

Load when: choosing Sheet, Dialog or AlertDialog or reviewing overlay title, dismissal, focus and destructive confirmation.

Also read: Shared component guidelines and Entity detail drawer for the drawer stack.

Do not load for: non-modal page sections or caller-owned persistence.

BEM identity: crm-sheet is emitted and its real side values map to crm-sheet--side-; the Deal Sheet browser check verified the base block. Approved size values target crm-sheet--size-small, --size-medium, --size-large, --size-xlarge, and --size-full; these size modifiers are not emitted yet. crm-dialog and crm-alert-dialog remain targets. Owned parts map to __backdrop, __content, __title, __description, __footer and __close only where that owner renders them.

Use Sheet for side-attached work, Dialog for bounded modal work, and AlertDialog for a confirmation that requires deliberate acknowledgement. All are composed from Base UI owners.

Approved drawer size standard

Use the canonical names small, medium, large, xlarge, and full. For a side Sheet, calculate width from the device's dynamic viewport, then cap it to the authenticated application's available surface: min(calc(100dvw - var(--app-sidebar-offset, 0px)), clamp(minimum, preferred-dvw, maximum)). On viewports narrower than 768px, every feature drawer becomes 100dvw so form controls and content do not collapse into a narrow strip.

For small through xlarge, the available-surface cap keeps the expanded sidebar visible and prevents the drawer crossing its interaction boundary. full is a separate fully blocking presentation and may cover the sidebar. Top and bottom Sheets use height, not this width scale. The mobile navigation Sheet continues to use --sidebar-width; it is not a feature drawer size.

The size API and modifiers are an approved design target, not a current source claim. Until SheetContent implements size, feature width classes are implementation drift. Do not invent another size name or treat an arbitrary pixel/vw class as a new standard.

Always provide a clear title and describe irreversible consequences. Put the safe escape action before or alongside the destructive action according to the existing footer order. Loading, API errors, and persistence remain caller-owned. Avoid nesting portaled overlays unless the shell explicitly guards that interaction.

Source: apps/frontend/src/components/ui/sheet.tsx, apps/frontend/src/components/ui/dialog.tsx, and apps/frontend/src/components/ui/alert-dialog.tsx.

Sidebar

Load when: changing the shared sidebar primitive, collapsed/mobile behavior, shortcut, navigation adapter or active state.

Also read: Application shell and Layout.

Do not load for: feature-page navigation actions or route authorization alone.

BEM identity: crm-sidebar is the target block. Stable owner parts may use __header, __content, __footer, __menu and __menu-button; collapsed/mobile/active modifiers must map to the provider or item state that actually owns them. Exact modifier placement is unassigned and the target block is not currently emitted.

Use the SidebarProvider and Sidebar composition from @/components/ui/sidebar only inside a shell. AppSidebar is the application adapter that supplies routes, role filtering, feedback, and session actions.

The provider supports open state, a Ctrl/Cmd+B shortcut, desktop widths (16rem expanded, 3rem icon), and an off-canvas mobile Sheet. SidebarMenuButton accepts isActive, variant, size, and tooltip; tooltip content is visible only in the collapsed desktop state.

Active navigation must derive from the router and its relevant search state. Role checks belong to AppSidebar or the feature's route policy, not the presentation primitive. The implementation exposes data-slot and data-sidebar hooks, not a verified project BEM identity.

Source: apps/frontend/src/components/ui/sidebar.tsx and apps/frontend/src/shared/ui/navigation/app-sidebar.tsx.

Tables and data grids

Load when: implementing a semantic table or AG Grid presentation and reviewing row, column, overflow or grid-theme behavior.

Also read: Data list and Shared component guidelines.

Do not load for: feature query, filtering, pagination or authorization logic.

BEM identity: crm-table targets the shared semantic table with __header, __body, __footer, __row, __head, __cell and __caption elements. crm-data-grid targets the AG Grid theme root. Neither target is currently emitted as the project BEM identity.

Use the shared Table family for small semantic tables. It wraps horizontal overflow and exports TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, and TableCaption.

Use AG Grid only when its grid capabilities are needed. Apply ag-theme-quartz; global CSS supplies semantic background, foreground, selection, border, field, typography, 48px-row, and 44px-header values. Keep grid-specific row semantics in the owning module rather than duplicating the global theme.

Rows are not automatically actions. If a row opens detail, make its interaction and keyboard behavior explicit, preserve selection behavior, and provide an alternate actionable control where needed. Handle loading, empty, errors, pagination, sorting, and permission-based columns in the feature owner.

Source: apps/frontend/src/components/ui/table.tsx and apps/frontend/src/styles/globals.css.

Accessibility

Load when: reviewing keyboard, focus, names/roles/states, error announcements, zoom/reflow, contrast or assistive-technology behavior.

Also read: Design guidelines for cross-cutting rules and the named component/pattern for exceptions.

Do not load for: token values or layout geometry without an accessibility decision.

Use native or Base UI semantics first. Every UI change must preserve a logical keyboard path and a visible focus indicator.

Verified behavior

Required checks

Gaps and limits

No WCAG target, contrast audit, screen-reader run, automated accessibility suite, or reduced-motion implementation was verified in this initialization. These are required review work, not passed checks.

Evidence

Source: apps/frontend/src/shared/ui/layouts/app-layout.tsx, apps/frontend/src/components/ui/form-row.tsx, apps/frontend/src/components/ui/inline-editable-value.tsx, apps/frontend/src/components/ui/entity-reference-field.tsx, apps/frontend/src/components/ui/dialog.tsx, and apps/frontend/src/components/ui/sheet.tsx.

Content and localization

Load when: writing or reviewing Vietnamese labels, actions, helper/error text, formatting, truncation, translation or RTL behavior.

Also read: Design guidelines and the named component/pattern when its content constraints differ.

Do not load for: component APIs or visual token selection alone.

The visible CRM UI is primarily Vietnamese, with a few existing English labels. Keep new copy in the language used by the owning screen unless a product decision changes it.

Rules

Not established

There is no centralized translation framework, terminology glossary, RTL policy, or long-text translation test in the inspected source. RTL is configured as false in components.json; do not infer RTL support.

Evidence

Source: apps/frontend/src/components/ui/form-row.tsx, apps/frontend/src/shared/ui/navigation/app-sidebar.tsx, apps/frontend/src/shared/ui/primitives/searchable-select.tsx, and apps/frontend/components.json.

Foundations

Use this index for visual values and structural layout. Cross-cutting usage rules live under Design guidelines.

Layout and responsive behavior

Load when: changing shell geometry, spacing/density, breakpoints, responsive forms, drawers or table overflow.

Also read: Application shell or the named component/pattern for owned responsive behavior.

Do not load for: color, copy or isolated component API decisions.

Use the shared application shell for authenticated routes and the auth layout for login/register routes. Do not reproduce shell padding, sidebar offset, or overlay behavior inside a feature page.

Verified rules

No project-wide page grid, spacing scale, or touch target minimum is presently established in source. The drawer scale is an approved design rule with a recorded implementation gap, not verified runtime adoption.

Evidence

Source: apps/frontend/src/shared/ui/layouts/app-layout.tsx, apps/frontend/src/components/ui/sidebar.tsx, apps/frontend/src/components/ui/form-row.tsx, apps/frontend/src/components/ui/sheet.tsx, and apps/frontend/src/components/ui/table.tsx.

Motion and interaction

Load when: changing hover, pressed, cursor, transition, loading animation or reduced-motion behavior.

Also read: Design guidelines and the affected component contract.

Do not load for: static token values or feature persistence logic.

Keep interaction feedback brief and functional. Existing controls use transition-colors, 100–300ms state transitions, and sheet/dialog entrance and exit animation classes.

Verified rules

Gap

No prefers-reduced-motion override is present in the inspected global stylesheet. Treat reduced-motion support as a follow-up requirement for any motion-heavy change.

Evidence

Source: apps/frontend/src/styles/globals.css, apps/frontend/src/components/ui/sheet.tsx, apps/frontend/src/components/ui/dialog.tsx, and apps/frontend/src/components/ui/skeleton.tsx.

Tokens and themes

Load when: selecting or changing semantic color, typography, spacing, radius, elevation, chart, sidebar or dark-theme values.

Also read: the named component or design guideline only when it constrains token use.

Do not load for: domain behavior, permissions or page actions.

Use semantic Tailwind utilities such as bg-primary, text-muted-foreground, and border-border; do not introduce hard-coded color values in shared UI when an existing role fits.

Verified implementation

Light tokens use a 12% color mix; dark mode changes the semantic values and uses 20% tints. Dark mode is implemented by a .dark ancestor.

The custom JSON manifest declares a Design Tokens Community Group schema URL but does not use DTCG token objects with $value/resolved $type, and no publish/import/translation boundary was verified. Treat it as a project lookup manifest, not proof of DTCG format conformance; DTCG interoperability validation remains not applicable until that boundary is intentionally adopted.

Usage rules

Evidence

Source: apps/frontend/src/styles/globals.css, apps/frontend/src/shared/constants/design-tokens-manifest.json, scripts/generate-tokens-manifest.mjs, apps/frontend/components.json, and apps/frontend/package.json.

Click chip màu để copy biến CSS, hoặc bấm icon 🤖 để copy câu lệnh Prompt ghép câu cho Agent.

Governance

Use this index for ownership, coverage, lifecycle, implementation drift and evidence decisions.

Naming and DOM identity

Load when: naming or renaming a reusable component, DOM block, stable element, variant/state modifier, prompt alias or framework symbol; also load when reviewing rendered component identity.

Also read: the component index for target blocks and implementation status, then only the named component contract and source owner.

Do not load for: token selection, page composition, copy changes or feature-only wrappers whose reusable owner and identity do not change.

Project standard and implementation status

Anphabe CRM uses crm as the project namespace for reusable rendered UI. Deal-flow owners now emit selected crm-* blocks: the create Sheet browser check verified crm-sheet, crm-card, crm-button, crm-deal-form and crm-deal-form-section; other affected blocks have source verification. Untouched owners remain targets in the component index.

The approved Sheet size names are small, medium, large, xlarge, and full. Their target mapping is size="" to crm-sheet--size- alongside the base crm-sheet; no size modifier is verified in source or rendered HTML yet. compact, standard, wide, workspace, arbitrary viewport widths, and translated labels are not canonical aliases.

BEM identity is a stable DOM inspection and lookup contract. Tailwind utilities continue to style the UI; data-slot may continue to support selectors. Neither one replaces the project BEM identity.

Grammar

Use lowercase kebab words. Name by stable UI responsibility, not color, record ID, DOM position or an incidental wrapper: use crm-button--variant-outline, not crm-blue-button, crm-row-42 or crm-sidebar-left-div.

A modifier maps to a real supported prop, variant or state and always coexists with the base block. It supplements rather than replaces native state, aria-*, data-* hooks or the component API.

Elements and composition

Component lookup contract

Every reusable rendered component row and owning concept records:

For example, Button emits crm-button; loading={true} maps to crm-button--loading and variant="outline" maps to crm-button--variant-outline. An owned icon part may use crm-button__icon when the owner explicitly renders it.

Adoption and verification

UI design system governance

Load when: deciding reuse versus a new owner, checking scope/coverage, resolving naming/BEM drift or assessing missing page contracts.

Also read: Validation when making an evidence or completion claim.

Do not load for: routine use of a known component with an unchanged contract.

This bundle is the single documentation entry for UI decisions in this checkout. It covers the React frontend only and is initialized from current source; it does not migrate or rely on docs/ui_bk/.

Design principles and status

Reuse and ownership

Naming standard and adoption status

The project grammar, lookup fields and verification rules live in Naming and DOM identity. The Deal audit verified crm-sheet, crm-card, crm-button and Deal form blocks in the rendered create Sheet; affected remaining blocks are verified in source. Untouched component families remain targets.

Coverage gaps

Compatibility

Preserve public imports and current variant APIs unless an approved feature intentionally changes them. Docs describe verified implementation and explicit proposals separately; source tests and runtime checks decide behavioral compliance.

UI documentation validation

Load when: validating UI docs or deciding whether source, unit, rendered, browser or accessibility evidence supports a claim.

Also read: only the changed concepts and their source/test owners.

Do not load for: routine implementation under a known, already verified contract.

Documentation-only change

1. Verify changed statements against the relevant source owner.

2. Check every local Markdown link and index reachability.

3. Run strict OKF validation against docs/ui.

4. Starting from the root index, test token, accessibility/content, component, pattern, page and reusable-component naming tasks; each must resolve to a bounded concept set.

5. Record unexecuted browser, accessibility, and behavior checks as limits.

For a naming task, the bounded route is Naming and DOM identity, the component index and only the named component contract/source owner.

UI behavior change

In addition to the documentation checks, run the narrowest relevant unit/integration test first, then typecheck/lint or a broader check when a shared contract changes. Inspect the affected UI in a real runtime when visual, focus, responsive, or rendered-DOM claims are made.

For BEM adoption, verify that the semantic rendered root contains its base block, elements follow ownership, nested component blocks remain independent and each modifier corresponds to the real prop/state. Source inspection alone does not establish rendered-DOM adoption.

For forms and association flows, verify initial, loading, empty, selected, editing, validation error, server error, disabled, success, cancel, and clear behavior that applies. Confirm clear does not delete the linked entity. For overlays, verify focus entry, focus return, Escape, outside-close behavior, and nesting safeguards.

For a drawer size implementation, verify each supported size at a viewport below 768px and at representative desktop widths. Confirm small through xlarge use the documented percentage/min/max rule, do not cross the expanded-sidebar application surface, do not create horizontal overflow, and render the matching crm-sheet--size-* modifier. Verify full separately as an intentionally fully blocking viewport surface. Source utility classes alone do not prove geometry.

Evidence boundary

OKF validation proves bundle structure and internal links only. Source inspection proves the checked implementation, not desired design compliance. A successful automated test does not prove browser layout, authenticated behavior, or screen-reader output unless that exact evidence was executed.

Uncommitted source may be documented as a working-tree extension only when that state is explicit. It does not become a stable public contract until the implementation and relevant checks are accepted.

Anphabe CRM design guidelines

Load when: making a cross-cutting UI decision, reviewing consistency, or choosing accessibility, feedback, content, hierarchy or semantic styling rules.

Also read: Tokens and themes for values, Components for a reusable owner, and Patterns for composed behavior.

Core rules

Accessibility and interaction

Use native or Base UI semantics, a logical keyboard path, visible focus, accessible names for icon-only actions, associated labels/errors and focus entry/return for overlays. Apply the detailed Accessibility and Motion and interaction contracts.

No project WCAG target, contrast audit, touch-target minimum, screen-reader run or reduced-motion implementation has been verified. These remain missing standards/checks rather than implied compliance.

Content and localization

Follow the owning screen's Vietnamese language, concise action verbs and repair-oriented errors. Use the detailed Content and localization contract. A translation framework, terminology glossary and RTL support are not established.

Do and don't

Evidence and limits

These guidelines summarize verified source and current documented contracts. They are not proof of visual consistency, WCAG compliance, responsive behavior or screen-reader output without the checks in Validation.

Design guidelines

Use this index for cross-cutting usage rules. Load a named component or pattern only when it has an exception to the shared guideline.

Anphabe CRM UI Design System

Start here for UI work. This bundle is a source-derived specification for the React frontend; it does not use docs/ui_bk/ as an authority.

Start here

Choose the task row and load only the linked concepts. Follow a conditional link only when the task actually needs that decision.

Groups

Current status

The current implementation uses React, Tailwind CSS 4, Base UI primitives, and CSS variables in apps/frontend/src/styles/globals.css. Generate the sole UI portal with okf-design-system view; its local artifact is docs/ui/view.html. docs/ui_bk/ was intentionally excluded.

Coverage map

Boundaries

Documentation does not grant permission to retrofit DOM classes, revise variants, or alter persistence. Domain modules retain data loading, authorization, validation, and save/cancel/delete behavior.

UI design-system log

2026-09-16 — Payment-ready Deal billing

The existing Deal form now requires payment-ready invoice identity when creating or adopting commerce and when explicitly editing commerce billing. Required semantics cover legal name, address, conditional company tax code, delivery email, and paired personal identity; unrelated edits preserve incomplete historical snapshots. The existing crm-deal-form owner and billing field controls are reused, with no new UI owner or DOM block.

2026-09-16 — Admin-only SePay account selection

Extended the existing crm-deal-payment-panel owner with a server-authorized masked account selector for ADMIN and a fail-closed disabled state. Non-Admins receive no alternate account catalog, disabled state removes actionable QR controls while retaining evidence/manual confirmation, and crm-deal-payment-panel--disabled plus crm-deal-payment-panel__account-selector map to the actual rendered states. No new UI owner or schema migration was introduced.

2026-09-15 — Legacy Deal billing hydration

Legacy Deal edit now hydrates a missing billing snapshot from the current authorized Contact and Account details, while a reusable invoice profile remains preferred and Lead identity remains the fallback. Existing billing snapshots and manual edits remain unchanged. The existing Deal form and crm-deal-form identity are reused; no new UI owner or DOM block was introduced.

2026-09-15 — Optional manual-payment note

Changed the existing Deal manual-payment confirmation dialog so its note field is optional. The shared Dialog, FormRow, Input, Textarea and Button owners and the existing crm-deal-payment-manual-confirmation identity remain unchanged; exact-amount validation, permissions, receipt creation and audit/settlement behavior stay enforced.

2026-09-14 — Independent Deal invoice status

Added an invoice lifecycle badge, Deal-table column and guarded detail control using the shared Badge, Select and Button owners. Invoice issuance remains independent from pipeline stage and is unavailable until the Deal is fully paid; the backend enforces the same invariant.

2026-09-15 — Legacy Deal edit parity

Extended the canonical Deal form so eligible ADMIN users can edit migration-era Pipeline/Stage, Lead-derived customer context, commerce and billing fields from full Deal detail data. Protected lifecycle/payment states remain disabled with an explanation, Pipeline and Stage submit atomically, PENDING request-affecting edits retain explicit supersession, and legacy commerce adoption remains intentional. No new UI owner or DOM block was introduced.

2026-09-14 — Audited manual Deal payment confirmation

Added a bounded Deal payment confirmation dialog using the shared Dialog, FormRow, Input, Textarea and Button owners. The Deal payment panel and dialog expose stable crm-* identities; exact-amount validation, role/ownership checks, Payment Receipt persistence, actor audit and confirmation time remain backend domain behavior.

2026-09-14 — Component contract previews

Added declarative preview coverage for every non-index concept in components/: 16 supported generic previews and three explicit documentation-only concepts. The generated portal now demonstrates contract states without executing CRM components, project data, or runtime behavior.

2026-09-14 — Generated portal is the sole UI catalog

Removed the authenticated /settings/ui-patterns route and its Settings link. The standalone docs/ui/view.html artifact, rebuilt with okf-design-system view, is now the single UI catalog surface; component contracts and product rendering remain the evidence for runtime behavior.

2026-09-14 — Shared CRM form primitives

Added fixed 160px FormRow layouts and the shared DetailEditableField owner. Account and Contact form headings now reuse FormSectionHeading; the former Account detail row remains a compatibility alias while cross-domain callers move to the shared owner. Domain schemas, autosave, permissions, and persistence are unchanged.

2026-09-13 — Lead form and detail alignment

Lead create/edit and detail surfaces now use explicit domain adapter names, shared FormSectionHeading, and source-verified crm-lead-* identity blocks. Conditional formatting uses a documented fixed CSS-variable palette while retaining compatibility with previously saved hexadecimal rules. The fixed Lead form/edit-row layouts remain domain adapters because they differ from the shared FormRow geometry. No Lead API, permissions, autosave, triage, association, or persistence behavior changed.

2026-09-13 — Device-relative drawer size standard

Approved five canonical feature-drawer sizes: small, medium, large, xlarge, and full. Sizes derive from dynamic device viewport width with minimum/maximum guardrails; feature drawers become full-width below 768px, and non-full sizes are capped to the authenticated application surface. The shared typed API and crm-sheet--size-* modifiers remain an explicit implementation gap; this documentation change did not migrate runtime callers.

2026-09-13 — Deal create alignment

Added source-level crm-* identity adoption for the shared controls used by Deal create/edit and for Deal-owned form regions. Introduced the shared FormSectionHeading, canonical DealForm, DealFormSection, DealLeadPicker, and shared SearchableSelect reuse. Focused regression tests verify Deal commerce and keyboard selection; browser-rendered evidence remains pending.

2026-09-13 — Update

Added the Naming and DOM identity contract with the crm-* namespace, block/element/modifier grammar, composition boundaries, component lookup targets, adoption status and rendered-output checks. Updated agent routes so naming guidance is loaded only for identity work. No UI runtime code or data changed.

2026-09-13 — Update

Re-ran okf-design-system init against the current frontend and repaired the root agent load map. Added the design-guideline route, shared component rules, task-oriented group lookups and per-concept loading directives. Updated the token contract for the custom manifest and recorded the working-tree EntityPicker clear extension as pending validation. No CRM runtime behavior or data was changed by this documentation initialization.

2026-09-13 — Initialization

Created the new UI design system from current frontend source. The legacy docs/ui_bk/ folder was deliberately excluded from discovery, migration, and editing.

Deal create/edit

Route: /deals Sheet create/edit flow. Load Deal form, then Sheets and dialogs only when changing its approved xlarge drawer size or overlay behavior.

The UI has no catalog data or API side effects. It preserves Deal association, pricing, payment and draft behavior. Review desktop and narrow mobile rendering separately; source and unit tests do not prove geometry.

Pages

Lead create and detail

Route: /leads create/edit Sheet and Lead detail surfaces.

Load Lead forms and detail adapters before changing presentation, then load shared Sheet, form, picker, or accessibility contracts only for the exact owner being changed. The Lead module owns service context, triage, permissions, autosave, association selection, drawer layering, and save behavior. Design-system adapters own only presentation and local interaction.

Review create and detail rendering without submitting a Lead. Unit tests protect service selection and detail autosave transitions, but do not prove responsive geometry or browser-rendered BEM classes.

Application shell

Load when: building or changing authenticated/auth layouts, sidebar/header composition, main content boundaries or global overlays.

Also read: Layout and responsive behavior and Sidebar when those owners change.

Do not load for: feature-page data, authorization or local form composition.

Use AppLayout for authenticated routes and AuthLayout for login/register route families. RootLayout only passes through the route outlet.

The authenticated order is: skip link, AppSidebar, SidebarInset, sticky header/global search, main outlet, quick-log action/sheet, then feedback dialog. The quick-log action is global UI state, not page-owned behavior. Keep feature pages inside the main outlet; do not introduce a competing fixed header or sidebar.

On mobile, Sidebar uses its Sheet behavior. The sidebar adapter filters role-gated navigation items, while route/API authorization remains authoritative. Test keyboard skip navigation and a collapsed sidebar whenever shell structure changes.

Source: apps/frontend/src/shared/ui/layouts/app-layout.tsx, apps/frontend/src/shared/ui/layouts/auth-layout.tsx, and apps/frontend/src/shared/ui/navigation/app-sidebar.tsx.

Data list

Load when: choosing Table versus AG Grid or defining collection loading, empty, error, row navigation and overflow behavior.

Also read: Tables and data grids for the shared visual owner.

Do not load for: unrelated forms, drawers or feature query semantics.

Choose the shared HTML Table for bounded semantic data and AG Grid for column behavior that needs grid capabilities. The feature owns queries, filtering, sorting, pagination, selection, empty/loading/error states, and authorization-sensitive columns.

Keep the column header visible, prevent long cells from widening the page, and distinguish row navigation from row selection. For an interactive row, ensure keyboard access and a visible focus treatment; the current generic Table only supplies visual row states. Use Tables and data grids for shared visual rules.

An empty state should state that no results are present and, where permitted, offer the next action. A skeleton is loading only; it is not an empty or error state.

Editable association

Load when: selecting, creating, displaying, navigating, editing, clearing or saving an Account, Contact or other entity relationship.

Also read: Entity references, the owning form component and its domain policy.

Do not load for: deleting an entity or editing unrelated scalar fields.

Use Entity references for the presentation owner. The domain owner follows this sequence:

1. Render the selected entity label or an explicit empty label.

2. Open edit using a specific accessible action; load/search choices under the caller's authorization.

3. Select or create the intended entity, then preserve the originating draft until the association save succeeds.

4. On clear, remove only the relationship after any required confirmation; never delete the referenced entity.

5. Keep a failed save visible and recoverable; do not silently revert unrelated draft fields.

The documented components expose loading, disabled, error, editing, selected, and empty presentation. They do not decide whether an association is required or whether its target can be created; that is domain policy.

Entity detail drawer

Load when: opening entity detail from a list/relationship, navigating nested drawer layers or guarding a portaled child modal.

Also read: Sheets and dialogs for overlay primitives and the named entity detail source.

Do not load for: standalone form sheets or page-level data rules.

Use EntityDrawerSheet for supported entity detail opened from a list or nested relationship. It currently displays one right Sheet at 90vw, which maps to the approved xlarge design target; the typed size contract is not implemented yet. It swaps the current stack layer in place and renders breadcrumbs with Back/Close actions.

The stack owner supplies stack, isOpen, onClose, onPop, onPush, and optional refresh after mutation. The drawer shell owns keyboard Escape: it pops a nested layer or closes the root layer. The child DrawerModalGuardContext suppresses Escape/outside close while a portaled child modal is open.

The current shell renders canonical Lead, Account, and Contact detail content; Campaign and Activity have explicit placeholder behavior. Do not claim they are full entity-detail contracts. Deletion callbacks close or pop the drawer and then invoke the caller's refresh hook.

Source: apps/frontend/src/shared/drawer/entity-drawer-sheet.tsx.

Patterns

Use this index when composing multiple components into a repeated workflow or layout.

Standalone page contracts are not yet documented. For a feature-page task, start with the closest pattern and inspect the named route/module source; do not infer that this index defines page-specific authorization, data or actions.