# Ankra design system

Intelligent by design. Operate with clarity.

## 1. Brand direction

Ankra is the operating workspace for people and AI managing infrastructure together. The identity should communicate judgment, structural clarity, and control. The interface should feel calm even when the underlying system is complicated.

The proposed faceted mark retains a geometric infrastructure character. Use the forest mark on light backgrounds and the lichen mark on dark backgrounds. The wordmark is lowercase, with restrained spacing. Approved proposed exports are in `assets/`.

- Mark grid: 24 × 28; consistent 1.65-unit stroke.
- Minimum mark size: 20 px. Below this, use a separately optically adjusted asset during implementation.
- Clear space: at least half the mark's width on every side.
- Preserve proportions. Do not stretch, add glow, apply gradients, or recolor the mark by operational status.
- Use lichen sparingly: identity, selected navigation detail, and highlights on dark surfaces. It is not a warning color or a default text color on white.
- Avoid gratuitous illustrations in operational screens. Diagrams must explain topology, dependencies, or evidence.

Voice is direct, capable, and specific: “Review plan,” “Connection interrupted,” “Change verified.” Explain the observed state, impact, and available action. Avoid anthropomorphic infrastructure states, fabricated confidence percentages, unsupported causal certainty, and claims that completion guarantees recovery.

## 2. Semantic color

Use the semantic role, not a hard-coded visual color. `design-tokens.json` and `design-tokens.css` are the machine-readable references.

| Role | Light | Dark | Use |
| --- | --- | --- | --- |
| canvas | #F5F7F4 | #0D1E17 | Workspace background |
| paper | #FFFFFF | #172E24 | Cards, headers, elevated surfaces |
| ink | #152B22 | #E6EEE7 | Primary text |
| muted | #617168 | #ADBDB1 | Secondary text |
| subtle | #657267 | #879D8D | Metadata and axis labels |
| line | #DCE4DC | #304A3B | Decorative dividers; not the sole boundary of a control |
| controlBorder | #7B8C80 | #769281 | Inputs and secondary-button boundaries |
| soft | #EDF1EC | #203B2D | Neutral selection and table headers |
| green | #13734E | #86D7AA | Primary action, success, evidence links |
| onPrimary | #FFFFFE | #11271E | Text/icons on a green primary action |
| greenSoft | #E7F3EB | #1D4230 | AI summaries, selected context, success tint |
| lime | #DEEF8E | #DEEF8E | Lichen brand accent |
| nav | #132B21 | #0B1913 | Persistent navigation |
| navActive | #294638 | #294638 | Active navigation background |
| navMuted | #A9BAAF | #A9BAAF | Secondary text on dark navigation |
| amber | #8A570F | #F0CA7B | Attention or approval required |
| red | #AE3B39 | #FFA8A4 | Failure, destructive action |
| blue | #315FAD | #A9C6FA | Running or informational state |
| purple | #7057A5 | #D1BEF2 | Optional specialized classification |

`onDanger` is near-white (#FFFEFF) in light mode and dark ink (#11271E) in dark mode. `text/inverse` stays white on intentionally dark surfaces in the Figma importer. These distinct roles prevent white labels disappearing against light mint or pink controls in dark mode.

Selected semantic text pairs exceed 4.5:1; control-border pairs exceed 3:1 in both themes. Exact measured results are in `qa/contrast-report.json`. This is a palette check, not certification of an implemented application. New combinations require fresh checks.

Do not encode state only in color. Pair status with a label, use an icon where helpful, and provide a description when the next step is not obvious. Avoid decorative red during noncritical empty states.

## 3. Typography

Inter is the UI family. Roboto Mono is for code, logs, resource identifiers, and diffs; browser SVGs use the system monospace fallback if it is not installed.

| Usage | Size / weight | Rule |
| --- | --- | --- |
| Brand display | 64–108 / 500 | Covers and direction boards only |
| Page title | 30 / 600 | One per page; avoid truncating the primary entity name |
| Section title | 17–20 / 600 | Clear local hierarchy |
| Card title | 16 / 600 | One line where practical |
| Body | 14–16 / 400 | Explanations, plans, and evidence summaries |
| Dense table/control | 12–13 / 400–600 | Operational density; do not scale the whole UI to fit more data |
| Metadata | 11–12 / 400–500 | Visible context, timestamps, source details |
| Code/log | 12–13 / 400 | Preserve indentation and horizontal scrolling |
| Eyebrow | 11 / 600 | Uppercase with 1.4 px tracking; use sparingly |

Default line height is 1.45. Display line height is intentionally tighter. The board uses 76 exact reusable Figma text styles to preserve the layouts; consolidate incidental display sizes when evolving the production library. Financial values, resource usage, timestamps, and row counts should use tabular figures in implementation.

For localization, allow 30–40% label growth and avoid assembling sentences from translated fragments. Full names and IDs remain available via detail, copy, and accessible labels even when visually truncated.

## 4. Layout and spacing

Desktop reference frames are 1440 × 1000. Navigation is 224 px wide; the global header is 64 px high. Main content begins at x=256, maintaining 32 px from the rail, and ends 32 px before the right edge. Entity context is visible in the header; local tabs carry entity depth.

Use a 4 px base with spacing tokens 4, 8, 12, 16, 24, 32, 48, 64. Cards use a 12 px radius; controls 7 px; small tags 6 px. Prefer borders and surface separation to shadows. Reserve elevation for popovers, panels, and dialogs.

The reference layouts use roughly 24 px card padding and 20–24 px gaps. Default data rows are 60–72 px; compact mode uses 40–48 px. Desktop controls may use 34–38 px in dense contexts, but provide larger hit areas where needed. Touch interactions require at least 44 × 44 px targets.

Responsive implementation guidance:

- At 1280 px and above, retain the full rail and multi-column content.
- At 1024–1279 px, allow a compact rail and stack auxiliary inspection panels when needed.
- At 768–1023 px, use an overlay navigation drawer and single primary content column; retain horizontally scrollable expert tables.
- Below 768 px, prioritize briefings, triage, approvals, search, and read access. Keep scope visible. Stack builders, wide diffs, and cluster provisioning may hand off to desktop.
- These breakpoints are proposed implementation rules. Only the two 390 × 844 mobile frames are separately art-directed here; there is no complete mobile equivalent of all desktop pages.

## 5. Components

Buttons use action verbs, one primary action per decision area, explicit destructive styling, disabled-state explanations, and visible loading state without width changes. Confirmation labels name the object and action. Read actions must not look like production mutations.

Forms have persistent labels, contextual help, field-specific errors, and an error summary after failed submission. Preserve entered values. Secret fields show masking; reveal and copy need explicit controls, permission checks, and audit policy. Never include secret values in analytics or AI context by default.

Tables preserve sort, filters, selection, pagination, and scope in navigation. Keep column headers visible, align numbers right, and expose bulk-action scope before confirmation. A refresh must not unexpectedly move the focused row. Unknown and unavailable values use an em dash plus an explanation—not zero.

Tabs switch views of the same entity. The rail changes product area. Drawers inspect an entity while preserving context; a full detail page owns durable deep links. Command search searches entities, destinations, and actions with visible scope and keyboard hints.

Charts need units, source, time window, freshness, legend, and an accessible table/export. Do not imply causality merely by placing two curves together. Illustrative board charts are placeholders for this contract, not measured time series. Forecasts and actuals must use distinguishable lines and labels; savings remain estimates until realized and measured.

Dependency graphs use labeled nodes, directed edges, deployment waves, readiness gates, and a text/list alternative. Keep unsaved versus saved drafts distinct. Selection opens an inspector; modifying the graph prepares a draft, not an immediate deployment.

## 6. AI experience contract

AI is a workspace capability, not a decorative chat bubble. Overview gives a daily briefing; Intelligence owns durable conversations, tasks, agents, runs, and plans; Inbox owns human decisions. Contextual Ask Ankra entry points retain the current entity, environment, cluster, and time range.

Every consequential action must expose:

1. The objective and scope, including cluster, namespace, resources, and environment.
2. The acting identity, required permission, autonomy mode, and human approver if required.
3. Observations with source links, timestamps, freshness, and unavailable evidence.
4. A proposed exact diff, preconditions, risk, estimated impact, and budget.
5. Expiry and revalidation behavior. Changed inputs invalidate the old approval.
6. Verification criteria and observation window.
7. A stop condition and recovery or rollback path, including irreversible side effects.
8. A durable receipt containing the approved plan, executed steps, failures, evidence, and outcome.

Use distinct states: Proposed → Needs approval → Running → Completed → Verified. Failed, partially failed, canceled, expired, stale, and budget-paused are separate branches. “Completed” is a tool/execution state; “Verified” requires the specified checks to pass.

No silent write escalation. A read-only conversation can prepare a plan but cannot execute a mutation. Setting a larger budget does not grant a broader permission. Untrusted repository content, runbooks, logs, and tool output are evidence, not authority to bypass approval.

## 7. Motion, accessibility, and recovery

Use 120 ms hover, 180 ms disclosure, and 240 ms panel transitions with opacity/transform only. Respect reduced motion. Do not continuously animate changing metrics. Never make motion the only signal that an operation is running.

Implementation target is WCAG 2.2 AA. Provide visible 2 px focus rings with 2 px offset; keep focused content unobscured. Trap focus within a modal and return it to its opener. Use correct table, tab, dialog, tree, and status semantics. Announce meaningful asynchronous changes politely; urgent failures require deliberate, nonrepeating announcements. Test keyboard and screen-reader workflows in the implemented product.

Preserve layout while loading. Show last-known freshness when disconnected. Distinguish an empty collection from filtered-out results and missing permission. A partially applied deployment lists successful and failed steps; retry is scoped to safe, idempotent work. Rollback explicitly states what cannot be reversed, such as database migrations or external effects.

Accessibility, localization, responsive resizing, and real-data scale need implementation validation beyond these artboards. The browser gallery is a presentation prototype, not the finished accessible product.