Coherence UI Skill

Data Sources

Three complementary sources provide a complete picture of every component and the design system. Consult the relevant source(s) for the task at hand.

1. Live API Manifest (primary — source of truth for API)

URL: https://coherence-ftekb0dcfpcjb3gv.b02.azurefd.net/cdn/latest/custom-elements.json

Fetch this URL to get the machine-readable API for any component. It follows the Custom Elements Manifest schema. For each component it provides:

• Attributes — exact names, types, defaults, descriptions
• Events — names, detail types
• Slots — names, descriptions
• CSS Custom Properties — all themeable hooks
• CSS Parts — all styleable internal parts
• Dependencies — which sub-components are auto-registered
• Class hierarchy — superclass and inherited members

How to look up a component: Find the module whose path matches src/components/<slug>/<slug>.ts, then read its declarations array for the entry with customElement: true.

Example: to look up cui-button, find the module with path: "src/components/button/button.ts" → its declaration is CuiButton.

2. Theme CSS — Design Tokens (source of truth for theming, colors, spacing, typography)

URL: https://coherence-ftekb0dcfpcjb3gv.b02.azurefd.net/cdn/latest/themes/cui/theme.css

Fetch this URL when answering questions about design tokens, theming, colors, spacing, typography, shadows, borders, animation timing, or component-level CSS variables. This auto-generated CSS file defines all CSS custom properties on :root / :host and is the single source of truth for token names and values.

What it contains:

How the theme CSS relates to component reference docs:

The theme CSS defines global defaults for ~578 tokens. Of those, about 51 are also documented in component reference files (mainly --button-*, --form-control-*, and --default-border). Component reference docs additionally list component-specific CSS custom properties (e.g. --accordion-item-*, --card-*, --dialog-*, --checkbox-*) that are not in the theme CSS — those are defined inside individual component stylesheets and can still be overridden. Use both sources together: the theme CSS for token values/names and the component refs for per-component override hooks.

When to fetch: Any time the user asks about available colors, spacing values, font sizes, shadow levels, how to theme a component, what CSS variables exist, or when you need the exact token name/value for a style.

3. Design Guidance References (supplementary — design, UX, and examples)

The reference docs below contain information the manifest does not have:

• When to use / when not to use a component
• Anatomy diagrams and layout rules
• Dos and don'ts
• Accessibility guidance specific to the component
• Code examples showing composition patterns
• Content/writing guidelines

Workflow

When the user asks to build UI or use a Coherence component:

1. Identify the component(s) needed from the index below or the manifest
2. Fetch the manifest to get the precise API (attributes, types, defaults, slots, events, CSS properties, dependencies)
3. Read the component reference file (if one exists) for design guidance, dos/don'ts, accessibility rules, and code examples
4. Combine both — use guidance to decide how to compose the UI; use the manifest as the source of truth for exact attribute names, types, and values
5. If no reference file exists, the manifest alone is sufficient for API usage — apply general Coherence accessibility and layout rules from the guides below
6. For theming, colors, spacing, typography, or shadows — fetch the theme CSS to get the exact token names and values
7. Output React by default — generate a React component (.tsx) using @charm-ux/cui/react wrappers. Only output plain HTML web components (<cui-*>) if the user explicitly requests it.

When composing a full page or layout, also read the relevant template and task flow references. For Azure portal pages specifically, start with the composition patterns in references/patterns/ — especially the Resource Page Shell — to avoid rebuilding the standard Azure chrome from scratch.

Component Index

Reference files contain design guidance and code examples only — not API details. Always fetch the manifest for API data.

Components with a reference file (66 — guidance available):

Components in the manifest only (API-only — no design guidance doc yet):

Templates

Page-level layout patterns. Read before composing full pages.

Task Flows

Multi-step interaction patterns. Read when implementing these specific user flows.

Composition Patterns

Reusable multi-component patterns extracted from real Azure portal prototypes. Read when composing Azure-style pages to avoid re-inventing common layouts.

When building an Azure portal page prototype, start with the Resource Page Shell pattern and customize it. It composes the Header, Side Nav, and Toolbar patterns together.

Shared Pattern Components (MUST USE — never re-implement)

These live React components exist in coherence-preview/src/patterns/ and must be imported instead of hand-building equivalent UI. Re-implementing them from scratch is a recurring mistake that produces inconsistent, non-dismissible, unstyleable results.

Anti-pattern: Do NOT create custom <button>, <div>, or <span> elements styled to look like Copilot suggestion pills. Always use the CopilotSuggestions pattern or pass the copilotSuggestions prop to PageHeader.

Page Scaffolds

Complete starter files for common Azure portal page types. Copy a scaffold to coherence-preview/src/ and customize the TODOs.

Flow Scaffolds

Multi-step or multi-page flow templates. These involve navigation between steps or pages.

Usage: Copy the scaffold or flow folder, rename it, fill in the TODO sections, and register it as an experiment in the preview app.

UX Guides

Cross-cutting design guidance. Read when the topic is relevant.

Styling Standards & Verification

Codified spacing, typography, color, border, shadow, state, layout, and accessibility rules extracted from the Coherence component library, manifest API, theme CSS, and all established patterns. Read before building custom UI and use the coherence-ui-verification skill to check compliance after.

| Resource | Reference | |----------|-----------|| | Styling Standards Registry | references/styling-standards.md | | UI Verification Skill (checklist) | ../../coherence-ui-verification/SKILL.md |

The verification skill cross-references three sources: the standards registry, the live API manifest, and the theme CSS. When it encounters a styling decision with no established standard, it asks the user whether to save it as a new rule.

Common Patterns

React Component Usage (default)

import { CuiButton } from '@charm-ux/cui/react';

export function SaveButton() {
  return <CuiButton appearance="primary">Save</CuiButton>;
}

Slots in React

Web component slots map to React props with the same name. Use the slot attribute on child elements:

import { CuiButton, CuiIcon } from '@charm-ux/cui/react';

export function AddItemButton() {
  return (
    <CuiButton>
      <CuiIcon slot="start" name="add" />
      Add item
    </CuiButton>
  );
}

Event Handling in React

Coherence React wrappers expose events as camelCase callback props. Use the onEventName pattern:

import { CuiDialog, CuiButton } from '@charm-ux/cui/react';
import { useRef } from 'react';

export function ConfirmDialog() {
  const dialogRef = useRef<HTMLElement>(null);

  return (
    <CuiDialog
      ref={dialogRef}
      heading="Confirm"
      onDialogRequestClose={(e) => {
        // Optionally prevent close: e.preventDefault();
      }}
    >
      <p>Are you sure?</p>
      <CuiButton slot="footer" appearance="primary">Yes</CuiButton>
      <CuiButton slot="footer">Cancel</CuiButton>
    </CuiDialog>
  );
}

Show/Hide with Triggers

import { CuiButton, CuiDrawer } from '@charm-ux/cui/react';

export function SettingsDrawer() {
  return (
    <>
      <CuiButton shows="my-drawer">Open Drawer</CuiButton>
      <CuiDrawer id="my-drawer" heading="Settings">
        <p>Drawer content</p>
      </CuiDrawer>
    </>
  );
}

CSS Custom Properties

Override component styling via CSS custom properties (same in React and HTML):

cui-button {
  --button-bg-color: var(--colorBrandBackground);
  --button-fg-color: var(--colorNeutralForegroundOnBrand);
  --button-border-radius: 8px;
}

Web Component Usage (alternate — only when explicitly requested)

<script type="module">
  import '@charm-ux/cui/dist/components/button/index.js';
</script>
<cui-button appearance="primary">Save</cui-button>

Accessibility Rules

Every component meets the Microsoft Accessibility Standards (MAS). When composing UIs:

1. Use cui-skip-to as the first tab stop on every page
2. Assign landmarks (<main>, <nav>, <header>) for skip-to navigation
3. Every interactive element must have a keyboard-accessible equivalent
4. All button text must pass 4.5:1 contrast; icons must pass 3:1
5. Labels cannot be substituted with placeholder text
6. Use aria-label or heading text for dialogs and drawers
7. Read references/guides/accessibility.md for comprehensive guidance

Previewing Components

A Vite + React preview app is set up at coherence-preview/. Use it to render any generated .tsx component in the browser.

Quick Start

1. Import the component in coherence-preview/src/main.tsx:

   import '@charm-ux/cui/dist/themes/cui/theme.css';
   import '@charm-ux/cui/dist/themes/cui/reset.css';
   import MyComponent from '../../MyComponent';
   

2. Start the dev server: cd coherence-preview && npx vite
3. Open the URL printed by Vite (usually http://localhost:5173)

The theme CSS imports provide all Coherence design tokens. The @charm-ux/cui/react wrappers auto-register their underlying web component definitions on first render.

Adding New Components to Preview

Edit coherence-preview/src/main.tsx — replace or add the component import and render it inside the root <div>. Vite HMR will update the browser automatically.

Icons & Fluent 2 Dependency

The cui-icon component relies on the Fluent 2 icon set. Icons referenced by name attribute must be registered first.

Critical: Import the Project Config

When generating code that uses <cui-icon name="..."> (or <CuiIcon name="..."> in React), you must ensure the project configuration is imported. Without it, icons will show a fallback question-mark and log a console warning.

For web components / plain HTML:

import '@charm-ux/cui/dist/project-config.js';
import '@charm-ux/cui/dist/components/icon/index.js';

For React: No extra import needed — the @charm-ux/cui/react wrappers auto-register icons.

For the preview app (coherence-preview/): Add this import to main.tsx:

import '@charm-ux/cui/dist/project-config.js';

Available Icon Names

After importing the project config, ~120 Fluent 2 icons are available. Simple names (prefer these — no network request needed): accessibility, add, alert, attach, bookmark, bot, calendar, chat, checkmark, clock, comment, copilot, copy, cut, delete, dislike, dismiss, edit, emoji, eye, filter, history, hourglass, info, like, link, location, mail, navigation, open, options, paste, pause, person, phone, pin, play, prohibited, resize, save, search, send, settings, share, snooze, star, stop, warning. Compound names: arrow-clockwise, arrow-download, arrow-left, arrow-maximize, arrow-minimize, arrow-move, arrow-redo-regular, arrow-reply, arrow-right, arrow-sort-down, arrow-sort-up, arrow-sync, arrow-undo-regular, arrow-upload, bookmark-filled, calendar-clock, checkmark-circle, chevron-double-left, chevron-double-right, chevron-down, chevron-left, chevron-up, circle-half-fill, code-regular, contact-card, copy-filled, cut-filled, dislike-filled, dismiss-circle, document-checkmark, document-edit, document-ribbon, emoji-meh, emoji-sad, error-circle, eye-off, filter-filled, highlight-regular, like-filled, link-edit-regular, link-regular, lock-closed, lock-open, more-horizontal, paste-filled, person-feedback, pin-filled, star-filled, start-line-horizontal, subtract-circle, tap-single, task-list, text-*-regular (all rich text icons), zoom-in, zoom-out.

Always prefer name over url when the icon exists in the registered set. Only fall back to Iconify URLs or url attribute for icons not available natively (e.g. terminal, stethoscope, globe, folder, server, database, etc.).

See references/components/icon.md for the full list and custom icon registration.

Mapping to charm-pilot

When working in the local charm-pilot codebase (@charm-ux/core):

The design guidance, slots, attributes, events, and CSS properties documented in the Coherence references apply to both. The ch-* components in charm-pilot are built following the same Coherence specifications.