Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

refactor(ui)!: separate primary hierarchy from accent color (#9129)

dev-rb46775b0ce0c8
diff --git a/.agents/rules/web/design-system.md b/.agents/rules/web/design-system.md
index fb23cc4f44..1917985f7d 100644
--- a/.agents/rules/web/design-system.md
+++ b/.agents/rules/web/design-system.md
@@ -51,12 +51,12 @@ construction. Browse them at `/app/component/ui` (Foundations → Controls).
(`[&_button]:size-8`); use an explicit `icon-*` size for icon actions. Put glyph
sizing on the rendered icon, not on Button or ancestor SVG selectors. Enforced
for wrappers by ast-grep `tsx-no-descendant-button-styles`, warning.
-- Use `variant="primary"` for the main create, save, submit, invite, approve, or continue action. Primary uses the theme accent; the separate accent variant stays removed. Use `neutral` for solid monochrome emphasis: black with white text in light themes, white with black text in dark themes. Home/AI chat, channel, and email Send actions use the shared neutral `SendButton`. Keep the shared New launcher (`ViewCreateButton`) on `variant="secondary" finish="raised"`, and retain secondary, outline, ghost, and danger variants for their own roles.
-- Quiet Back, Close, Cancel, and unframed inline utility actions use explicit `variant="ghost"`; omitting the variant opts into primary emphasis. Keep intentional framed groups and selected-state actions in their own variants. Size every rendered glyph explicitly, including children passed through action wrappers; Button does not size descendant SVGs.
+- Use `variant="primary"` for the main create, save, submit, invite, approve, or continue action. Primary is solid neutral: black with white text in light themes, white with black text in dark themes. Keep existing primary consumers on `primary`, including selected-state controls. Use explicit `variant="accent"` only for separately intended theme-color emphasis. Home/AI chat, channel, and email Send actions use the shared primary `SendButton`. Keep the shared New launcher (`ViewCreateButton`) on `variant="secondary" finish="raised"`, and retain secondary, outline, ghost, and danger variants for their own roles.
+- Quiet Back, Close, Cancel, and unframed inline utility actions use explicit `variant="ghost"`; omitting the variant opts into solid neutral primary emphasis, not accent. Keep intentional framed groups and selected-state actions in their own variants. Size every rendered glyph explicitly, including children passed through action wrappers; Button does not size descendant SVGs.
- Selected reaction chips are a deliberate local exception: `ReactionChip` uses `appearance="bare"` with accent-tint, accent-text, and overlay classes to preserve its soft selected treatment without a new Button variant. Keep unselected reactions on `secondary`.
- Current application Button usages trial `secondary` instead of `outline`, including shared wrappers and groups. Keep the outline API and canonical Button gallery examples; do not change outline variants on badges, inputs, or other components.
-- Settings actions that previously used inverse-filled `cta` styling use explicit `variant="neutral"`, including creation, runtime setup, billing, invitation, and signature-save actions. Keep existing accent, ghost, and destructive actions in their own roles; do not recolor Button descendants from `SettingsPage`.
-- Primary, neutral, secondary, danger, and success Buttons and ButtonGroup frames automatically use the raised desktop finish and shared glass on touch. Use `finish="flat"` to opt out or `finish="raised"` to frame a ghost/link action. Outline variants, bare controls, and grouped segments always stay flat.
+- Settings actions that previously used inverse-filled `cta` styling use explicit `variant="primary"`, including creation, runtime setup, billing, invitation, and signature-save actions. Keep existing accent, ghost, and destructive actions in their own roles; do not recolor Button descendants from `SettingsPage`.
+- Primary, accent, secondary, danger, and success Buttons and ButtonGroup frames automatically use the raised desktop finish and shared glass on touch. Use `finish="flat"` to opt out or `finish="raised"` to frame a ghost/link action. Outline variants, bare controls, and grouped segments always stay flat.
- Follow the [Button and ButtonGroup contract](ui-primitives.md#button-and-buttongroup)
for accessible names, tooltips, sizing, explicit segments, and activation behavior.
- **FE-64** Components own their state treatments: desktop Tabs share a flat rounded track with an inset selected pill;
diff --git a/.agents/rules/web/ui-primitives.md b/.agents/rules/web/ui-primitives.md
index f2991a213e..0faa784ea4 100644
--- a/.agents/rules/web/ui-primitives.md
+++ b/.agents/rules/web/ui-primitives.md
@@ -76,7 +76,7 @@ Applies to `apps/web/src/components/ui`, including ports from shadcn-solid.
native inputs, accessible labels, controlled/uncontrolled state, and keyboard behavior.
- Keep unchecked checkbox and radio faces transparent. Checked and indeterminate
controls use the accent fill. Checkbox marks and radio indicators share the
- primary Button's `button-primary-ink` token.
+ accent Button's `button-accent-ink` token.
- Set checkbox/radio size on the root: `sm` is 14px, `md` (default) is 16px,
and `lg` is 20px. `ToggleSwitch` tracks use `xs` 28×14px, `sm` (default)
32×16px, and `md` 40×20px. Do not resize internal SVGs or override selection
diff --git a/apps/web/src/components/ui/components/Button.docs.tsx b/apps/web/src/components/ui/components/Button.docs.tsx
index 53cafaa32a..fbb17ae3e8 100644
--- a/apps/web/src/components/ui/components/Button.docs.tsx
+++ b/apps/web/src/components/ui/components/Button.docs.tsx
@@ -12,7 +12,7 @@ import { ButtonGroup } from './ButtonGroup';
const VARIANTS: ButtonVariant[] = [
'primary',
- 'neutral',
+ 'accent',
'secondary',
'outline',
'ghost',
@@ -244,7 +244,7 @@ export default defineDoc({
name: 'Button',
category: 'Actions',
description:
- 'Shared action control with semantic materials, automatic desktop elevation and touch glass, explicit icon sizes, and configurable tooltips.',
+ 'Shared action control with solid neutral primary, explicit accent emphasis, automatic desktop elevation and touch glass, explicit icon sizes, and configurable tooltips.',
status: 'beta',
exports: ['Button', 'ButtonGroup'],
import: "import { Button, ButtonGroup } from '@ui';",
diff --git a/apps/web/src/components/ui/components/Button.tsx b/apps/web/src/components/ui/components/Button.tsx
index 9bb4e31a57..7358d2069f 100644
--- a/apps/web/src/components/ui/components/Button.tsx
+++ b/apps/web/src/components/ui/components/Button.tsx
@@ -23,8 +23,8 @@ import { Tooltip } from './Tooltip';
const buttonFrames = {
primary:
'bg-button-primary-bg text-button-primary-ink border-transparent shadow-button',
- neutral:
- 'bg-button-neutral-bg text-button-neutral-ink border-transparent shadow-button',
+ accent:
+ 'bg-button-accent-bg text-button-accent-ink border-transparent shadow-button',
secondary: cn(
'bg-button-secondary-bg text-ink-muted border-border-secondary dark-mode:border-transparent shadow-button',
'light-mode:not-data-disabled:active:border-border-secondary light-mode:aria-pressed:border-border-secondary light-mode:popup-open:border-border-secondary'
@@ -54,9 +54,9 @@ const buttonStyles = createVariants(
'not-data-disabled:hover:bg-button-primary-hover not-data-disabled:active:bg-button-primary-pressed aria-pressed:bg-button-primary-pressed aria-pressed:not-data-disabled:hover:bg-button-primary-pressed popup-open:bg-button-primary-pressed popup-open:not-data-disabled:hover:bg-button-primary-pressed',
buttonPressedStyles
),
- neutral: cn(
- buttonFrames.neutral,
- 'not-data-disabled:hover:bg-button-neutral-hover not-data-disabled:active:bg-button-neutral-pressed aria-pressed:bg-button-neutral-pressed aria-pressed:not-data-disabled:hover:bg-button-neutral-pressed popup-open:bg-button-neutral-pressed popup-open:not-data-disabled:hover:bg-button-neutral-pressed',
+ accent: cn(
+ buttonFrames.accent,
+ 'not-data-disabled:hover:bg-button-accent-hover not-data-disabled:active:bg-button-accent-pressed aria-pressed:bg-button-accent-pressed aria-pressed:not-data-disabled:hover:bg-button-accent-pressed popup-open:bg-button-accent-pressed popup-open:not-data-disabled:hover:bg-button-accent-pressed',
buttonPressedStyles
),
secondary: cn(
@@ -181,6 +181,7 @@ export type ButtonProps<T extends ValidComponent = 'button'> = PolymorphicProps<
/**
* Actions use Button; navigation uses anchors. Framed variants adapt to the device.
+ * @do Use primary for solid neutral emphasis and accent for explicit theme-color emphasis.
* @do Set aria-label for icon-only actions and use an explicit icon-* size.
* @do Use tooltip strings for content only, or options for hotkeys and placement.
* @dont Use Button for links or size descendant icons through the control.
diff --git a/apps/web/src/components/ui/components/ButtonGroup.tsx b/apps/web/src/components/ui/components/ButtonGroup.tsx
index 533eec37db..5020213093 100644
--- a/apps/web/src/components/ui/components/ButtonGroup.tsx
+++ b/apps/web/src/components/ui/components/ButtonGroup.tsx
@@ -26,6 +26,7 @@ const ButtonGroupContext = createContext<ButtonGroupContextValue>();
export const useButtonGroupContext = () => useContext(ButtonGroupContext);
export type ButtonGroupProps = Omit<ComponentProps<'div'>, 'size'> & {
+ /** Softer secondary frame by default; primary is solid neutral and accent is explicit. */
variant?: ButtonVariant;
/** The shared frame adapts by default; segments always stay flat. */
finish?: ButtonFinish;
diff --git a/apps/web/src/components/ui/components/Checkbox.tsx b/apps/web/src/components/ui/components/Checkbox.tsx
index a735e6b88b..4196e82aa8 100644
--- a/apps/web/src/components/ui/components/Checkbox.tsx
+++ b/apps/web/src/components/ui/components/Checkbox.tsx
@@ -22,7 +22,7 @@ type LabelProps = ComponentProps<typeof KobalteCheckbox.Label>;
const CheckboxSizeContext = createContext((): CheckboxSize => 'md');
const checkboxVariants = createVariants(
- 'inline-grid shrink-0 place-items-center rounded border border-border-primary bg-transparent text-button-primary-ink data-checked:border-accent data-checked:bg-accent data-indeterminate:border-accent data-indeterminate:bg-accent',
+ 'inline-grid shrink-0 place-items-center rounded border border-border-primary bg-transparent text-button-accent-ink data-checked:border-accent data-checked:bg-accent data-indeterminate:border-accent data-indeterminate:bg-accent',
{
size: {
sm: 'size-3.5',
diff --git a/apps/web/src/components/ui/components/RadioGroup.tsx b/apps/web/src/components/ui/components/RadioGroup.tsx
index 75091db7de..25e2ceb604 100644
--- a/apps/web/src/components/ui/components/RadioGroup.tsx
+++ b/apps/web/src/components/ui/components/RadioGroup.tsx
@@ -47,7 +47,7 @@ function RadioGroupItemIndicator(props: ItemIndicatorProps) {
return (
<KobalteRadioGroup.ItemIndicator
class={cn(
- 'rounded-full bg-button-primary-ink',
+ 'rounded-full bg-button-accent-ink',
radioSizes[size()].indicator,
local.class
)}
diff --git a/apps/web/src/components/ui/components/SendButton.tsx b/apps/web/src/components/ui/components/SendButton.tsx
index 8445b0fa6a..d76b34dc40 100644
--- a/apps/web/src/components/ui/components/SendButton.tsx
+++ b/apps/web/src/components/ui/components/SendButton.tsx
@@ -38,7 +38,7 @@ export function SendButton(props: SendButtonProps) {
return (
<Button
- variant="neutral"
+ variant="primary"
size="icon-md"
draggable={false}
aria-label={
diff --git a/apps/web/src/features/settings/Agents.tsx b/apps/web/src/features/settings/Agents.tsx
index a61dde5548..c7f0ffff3b 100644
--- a/apps/web/src/features/settings/Agents.tsx
+++ b/apps/web/src/features/settings/Agents.tsx
@@ -346,7 +346,7 @@ export function Agents(props: {
</p>
</div>
<Button
- variant="neutral"
+ variant="primary"
size="sm"
onClick={() => setCreating(true)}
>
diff --git a/apps/web/src/features/settings/ApiKeys.tsx b/apps/web/src/features/settings/ApiKeys.tsx
index 2f4953d4d8..9b359ae208 100644
--- a/apps/web/src/features/settings/ApiKeys.tsx
+++ b/apps/web/src/features/settings/ApiKeys.tsx
@@ -59,7 +59,7 @@ export function ApiKeys() {
disabled={!atLimit()}
>
<Button
- variant="neutral"
+ variant="primary"
size="sm"
disabled={createDisabled()}
onClick={openCreate}
@@ -107,7 +107,7 @@ export function ApiKeys() {
</div>
<Button
class="mt-4"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={openCreate}
>
diff --git a/apps/web/src/features/settings/BotSettingsList.tsx b/apps/web/src/features/settings/BotSettingsList.tsx
index af0d5ad0d2..c75b3f8346 100644
--- a/apps/web/src/features/settings/BotSettingsList.tsx
+++ b/apps/web/src/features/settings/BotSettingsList.tsx
@@ -68,7 +68,7 @@ export function BotSettingsList(props: {
title="Bots"
description="A bot is an account your program uses to read and send channel messages. Create a bot, add it to channels, then use its token with the Macro SDK to control it."
actions={
- <Button variant="neutral" size="sm" onClick={props.onCreate}>
+ <Button variant="primary" size="sm" onClick={props.onCreate}>
<PlusIcon class="size-3 touch:size-6 shrink-0 pointer-events-none" />
Create bot
</Button>
@@ -103,7 +103,7 @@ export function BotSettingsList(props: {
</div>
<Button
class="mt-4"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={props.onCreate}
>
diff --git a/apps/web/src/features/settings/CursorConnectPage.tsx b/apps/web/src/features/settings/CursorConnectPage.tsx
index 4c769667e8..e9de496293 100644
--- a/apps/web/src/features/settings/CursorConnectPage.tsx
+++ b/apps/web/src/features/settings/CursorConnectPage.tsx
@@ -236,7 +236,7 @@ export function CursorConnectPage(props: { onClose: () => void }) {
</Button>
<Button
type="submit"
- variant="neutral"
+ variant="primary"
size="sm"
disabled={!apiKey().trim() || saveKey.isPending}
>
@@ -247,7 +247,7 @@ export function CursorConnectPage(props: { onClose: () => void }) {
>
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={props.onClose}
>
diff --git a/apps/web/src/features/settings/Harness.tsx b/apps/web/src/features/settings/Harness.tsx
index 95e8ed74fa..d936e1bdc7 100644
--- a/apps/web/src/features/settings/Harness.tsx
+++ b/apps/web/src/features/settings/Harness.tsx
@@ -134,7 +134,7 @@ export function Harness(
backLabel={props.backLabel ?? 'Agents'}
actions={
<Button
- variant="neutral"
+ variant="primary"
size="sm"
onClick={() => setPairingDialog({})}
>
diff --git a/apps/web/src/features/settings/RuntimePairingPage.tsx b/apps/web/src/features/settings/RuntimePairingPage.tsx
index 6885c2e987..f21837fd5d 100644
--- a/apps/web/src/features/settings/RuntimePairingPage.tsx
+++ b/apps/web/src/features/settings/RuntimePairingPage.tsx
@@ -326,7 +326,7 @@ export function RuntimePairingPage(props: {
<Match when={approved()}>
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={props.onClose}
>
@@ -355,7 +355,7 @@ export function RuntimePairingPage(props: {
</Button>
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
disabled={!canApprove()}
onClick={() => fireAndForget(approve(), 'runtime-pairing')}
@@ -384,7 +384,7 @@ export function RuntimePairingPage(props: {
</Button>
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
disabled={codeInput().trim().length === 0}
onClick={lookUp}
diff --git a/apps/web/src/features/settings/Tags.tsx b/apps/web/src/features/settings/Tags.tsx
index 626735023c..17df9d8c9b 100644
--- a/apps/web/src/features/settings/Tags.tsx
+++ b/apps/web/src/features/settings/Tags.tsx
@@ -313,7 +313,7 @@ export function Tags() {
title="Tags"
description="Manage personal labels and shared team labels."
actions={
- <Button variant="neutral" size="sm" onClick={() => openCreate('user')}>
+ <Button variant="primary" size="sm" onClick={() => openCreate('user')}>
<PlusIcon class="size-4" />
New tag
</Button>
diff --git a/apps/web/src/features/settings/TeamMembers.tsx b/apps/web/src/features/settings/TeamMembers.tsx
index f990c7777d..c3609f37b3 100644
--- a/apps/web/src/features/settings/TeamMembers.tsx
+++ b/apps/web/src/features/settings/TeamMembers.tsx
@@ -383,7 +383,7 @@ export function TeamMembers(props: { team: TeamSummary }) {
{/* Inverted (black on light, white on dark) so inviting is the
page's primary action. */}
<Button
- variant="neutral"
+ variant="primary"
class="text-[15px]"
onClick={() => setShowInviteModal(true)}
>
diff --git a/apps/web/src/features/settings/components/billing-plan-card.tsx b/apps/web/src/features/settings/components/billing-plan-card.tsx
index 38d9db7111..75d70324f8 100644
--- a/apps/web/src/features/settings/components/billing-plan-card.tsx
+++ b/apps/web/src/features/settings/components/billing-plan-card.tsx
@@ -92,7 +92,7 @@ export function BillingPlanCard(props: {
<Show when={props.onSelectPlan}>
<Button
class="w-full py-1.5 px-3 @sm/plan-card:w-auto @sm/plan-card:justify-self-end"
- variant="neutral"
+ variant="primary"
disabled={
props.state.pending ||
(!props.state.hasPaid &&
diff --git a/apps/web/src/features/settings/components/local-runtime-card.tsx b/apps/web/src/features/settings/components/local-runtime-card.tsx
index 059d0e632e..99128dba00 100644
--- a/apps/web/src/features/settings/components/local-runtime-card.tsx
+++ b/apps/web/src/features/settings/components/local-runtime-card.tsx
@@ -222,7 +222,7 @@ export function LocalRuntimeCard() {
</p>
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={() => setSetup({ running: snapshot() })}
>
@@ -295,7 +295,7 @@ export function LocalRuntimeCard() {
<div class="mt-4">
<Button
type="button"
- variant="neutral"
+ variant="primary"
size="sm"
onClick={() => setSetup({})}
>
diff --git a/apps/web/src/features/settings/components/signature-form.tsx b/apps/web/src/features/settings/components/signature-form.tsx
index 43f96eb40b..d7776c55ec 100644
--- a/apps/web/src/features/settings/components/signature-form.tsx
+++ b/apps/web/src/features/settings/components/signature-form.tsx
@@ -81,7 +81,7 @@ export function SignatureForm(props: {
</Button>
<Show when={!props.mobile}>
<Button
- variant="neutral"
+ variant="primary"
size="md"
disabled={!props.dirty || props.pending || props.importing}
onClick={props.onSave}
diff --git a/apps/web/src/features/theme/utils/buttonTheme.ts b/apps/web/src/features/theme/utils/buttonTheme.ts
index b6df10473f..561645c036 100644
--- a/apps/web/src/features/theme/utils/buttonTheme.ts
+++ b/apps/web/src/features/theme/utils/buttonTheme.ts
@@ -33,7 +33,7 @@ export function buttonAccentVars(
const useDarkInk = luminance > DARK_INK_LUMINANCE_THRESHOLD;
return {
- '--button-primary-ink': useDarkInk ? BLACK : WHITE,
- '--button-primary-state-mix': useDarkInk ? WHITE : BLACK,
+ '--button-accent-ink': useDarkInk ? BLACK : WHITE,
+ '--button-accent-state-mix': useDarkInk ? WHITE : BLACK,
};
}
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index c176025f36..54ea20fe4e 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -642,15 +642,15 @@ body.tauri-ios {
--divider: oklch(1 0 0 / 4%);
/* Button materials. */
- --button-primary-bg: var(--color-accent);
- --button-primary-ink: white;
- --button-primary-state-mix: black;
- --button-primary-hover: color-mix(in srgb, var(--button-primary-bg) 82%, var(--button-primary-state-mix));
- --button-primary-pressed: color-mix(in srgb, var(--button-primary-bg) 72%, var(--button-primary-state-mix));
- --button-neutral-bg: white;
- --button-neutral-ink: black;
- --button-neutral-hover: color-mix(in srgb, var(--button-neutral-bg) 82%, var(--button-neutral-ink));
- --button-neutral-pressed: color-mix(in srgb, var(--button-neutral-bg) 72%, var(--button-neutral-ink));
+ --button-primary-bg: white;
+ --button-primary-ink: black;
+ --button-primary-hover: color-mix(in srgb, var(--button-primary-bg) 82%, var(--button-primary-ink));
+ --button-primary-pressed: color-mix(in srgb, var(--button-primary-bg) 72%, var(--button-primary-ink));
+ --button-accent-bg: var(--color-accent);
+ --button-accent-ink: white;
+ --button-accent-state-mix: black;
+ --button-accent-hover: color-mix(in srgb, var(--button-accent-bg) 82%, var(--button-accent-state-mix));
+ --button-accent-pressed: color-mix(in srgb, var(--button-accent-bg) 72%, var(--button-accent-state-mix));
--button-focus: var(--color-edge-focus, var(--color-accent));
--button-elevated-outline: var(--glass-desktop-outline);
--button-elevated-top-edge: var(--glass-desktop-top-edge);
@@ -719,8 +719,8 @@ body.tauri-ios {
--divider: oklch(0 0 0 / 4%);
/* Button materials. */
- --button-neutral-bg: black;
- --button-neutral-ink: white;
+ --button-primary-bg: black;
+ --button-primary-ink: white;
/* Keep hover and pressed shading neutral over the lightly tinted face. */
--button-secondary-bg: var(--button-secondary-face);
--button-secondary-hover: color-mix(in srgb, var(--button-secondary-face), black 4%);
@@ -782,10 +782,10 @@ body.tauri-ios {
--color-button-primary-hover: var(--button-primary-hover);
--color-button-primary-pressed: var(--button-primary-pressed);
--color-button-primary-ink: var(--button-primary-ink);
- --color-button-neutral-bg: var(--button-neutral-bg);
- --color-button-neutral-ink: var(--button-neutral-ink);
- --color-button-neutral-hover: var(--button-neutral-hover);
- --color-button-neutral-pressed: var(--button-neutral-pressed);
+ --color-button-accent-bg: var(--button-accent-bg);
+ --color-button-accent-ink: var(--button-accent-ink);
+ --color-button-accent-hover: var(--button-accent-hover);
+ --color-button-accent-pressed: var(--button-accent-pressed);
--color-button-secondary-bg: var(--button-secondary-bg);
--color-button-secondary-hover: var(--button-secondary-hover);
--color-button-secondary-pressed: var(--button-secondary-pressed);
diff --git a/apps/web/src/lib/core/internal/ThemeDebug.tsx b/apps/web/src/lib/core/internal/ThemeDebug.tsx
index 84dcafe837..35d4760524 100644
--- a/apps/web/src/lib/core/internal/ThemeDebug.tsx
+++ b/apps/web/src/lib/core/internal/ThemeDebug.tsx
@@ -32,8 +32,14 @@ const BUTTON_VARIANTS = [
'secondary',
'danger',
'primary',
+ 'accent',
+] as const;
+const BUTTON_CONTENT_VARIANTS = [
+ 'outline',
+ 'secondary',
+ 'primary',
+ 'accent',
] as const;
-const BUTTON_CONTENT_VARIANTS = ['outline', 'secondary', 'primary'] as const;
const BUTTON_ICON_SIZES = {
sm: 'icon-sm',
md: 'icon-md',
diff --git a/docs/agent-guide/ui-conventions.md b/docs/agent-guide/ui-conventions.md
index 9a83c8708d..288e6fbe31 100644
--- a/docs/agent-guide/ui-conventions.md
+++ b/docs/agent-guide/ui-conventions.md
@@ -42,8 +42,8 @@ shared Button touch targets; do not resize these controls through classes.
On touch devices, low-emphasis header actions remain borderless with their
existing hover and pressed states. Emphasized variants retain their treatment,
including an active call's green ink. Button size does not change variant colors
-or framing. Primary, neutral, secondary, danger, and success Buttons automatically use raised desktop styling and glass on touch. Use `finish="flat"` to opt out, or `finish="raised"` to frame a ghost/link action. Outline Buttons always stay flat, including when a finish is supplied.
-Primary Buttons use the theme accent and its resolved contrast color. Use `neutral` for solid monochrome emphasis (black in light themes, white in dark themes), and secondary for softer neutral actions. Current Button usages trial secondary instead of outline; the outline API and canonical gallery examples remain available. The separate accent variant remains removed.
+or framing. Primary, accent, secondary, danger, and success Buttons automatically use raised desktop styling and glass on touch. Use `finish="flat"` to opt out, or `finish="raised"` to frame a ghost/link action. Outline Buttons always stay flat, including when a finish is supplied.
+Primary Buttons use solid monochrome emphasis (black in light themes, white in dark themes) for main actions such as create, save, submit, invite, and continue. Do not use accent merely because an action is primary. Accent Buttons use the theme accent and its resolved contrast color; accent emphasis is always explicit. Omitted variants use primary, and secondary remains the softer neutral action. Current Button usages trial secondary instead of outline; the outline API and canonical gallery examples remain available.
Button API and composition details live in the
[shared primitive contract](../../.agents/rules/web/ui-primitives.md#button-and-buttongroup).
Inline calendar-invitation text actions remove the transparent border to keep alignment.