# Design System

Our starting hypothesis for public and signed-in web pages. Use these defaults, learn from real pages, and keep refining them to remove complexity and ambiguity.

## Scope

Network, Connectors, Settings, sign-in and invite flows, Setup and the refreshed public pages use this foundation.

Shared web components live in app/components/web/. Signed-in routes in app/(web)/ and Setup in app/(connect)/ reuse existing auth, hooks and services. Public routes use the shared page frame and navigation in app/components/marketing/. The existing interface, including new admin dashboard pages, continues using @noticed/ui.

Read both folders’ AGENTS.md files. Use CSS Modules and [data-web-ui], including portal content. Reuse explicitly allowed shared Button, Input, Icon, LogoDevImage and brand NoticedMark exports through scoped web adapters. Keep legacy page layouts and unscoped style changes out of the new system. Shared root CSS and providers still apply; check inheritance and transitive UI dependencies.

## Layout and spacing

Use consistent widths and alignment, open sections and restrained dividers. Reserve cards for grouped content. Luma informs the geometry. Network and Connectors share the foundation.

App content tops out at 788px for standard views and 960px for wide views, with 16px side gutters. Align the app header with the page content. Connectors uses the wide layout: LinkedIn and X above Google and Microsoft in two columns, stacking in that reading order below 832px. Providers use the shared card recipe with 12px vertical and 16px horizontal row padding, no extra wrapper padding, and 16px between card rows. Multiple-account groups start collapsed; single accounts stay visible. The iPhone prompt is a separate compact card 96px below the providers, aligned to one column on desktop and full width on mobile.

Public pages use the width that fits the content. Help, Brand Guidelines and its agent/image references, Design System, Developers and Pricing use 788px. Blog uses 960px for the index and 672px for articles. Privacy, Terms and Data and providers also use the 672px reading column. These layouts use 16px side gutters on mobile and reserve 32px on desktop before applying the content cap. The homepage and event guides use wider sections where the content calls for it.

All app pages use 44px between the header and page title, matching Luma Settings. Use the shared --web-page-top token for existing and future adopting pages. Settings uses 24px from title to tabs, 24px from tabs to content, and 24px on each side of section dividers. Within sections it uses 16px heading-to-content and form-row gaps, 4px label-to-input gaps, 16px between form columns, and 12px vertical and 16px horizontal grouped-row padding.

## Typography

App typography uses Switzer at 24px for page titles, 18px for section titles, 14px for descriptions and Settings rows, 13px for controls and dense Network/Connectors rows, and 12px for chips and supporting details. Use sentence case for interface titles. The lowercase noticed wordmark uses Fraunces.

Use 14px for descriptions, inputs, navigation and Settings card rows; 13px for tabs, menus, filters, buttons and dense Network/Connectors card rows; 12px for chips, footnotes and small status messages. Page and section titles are semibold. Network cards pair available company and role with an identifier when a work detail is missing. Keep the date chips aligned in their own row. Additional identifiers use icon-and-text popover rows. LinkedIn and X identifiers link to profiles with plain text styling and visible keyboard focus. Body, controls and connector rows are regular; use medium for person names and active navigation. Text inside a section must not compete with its heading.

Use one shared typography vocabulary for public and authenticated pages. The foundation reuses the existing text-display (24px), text-title-sm (18px), type-sm (14px), text-row (13px) and text-label (12px) tokens; apply weight by role. Public reference pages use 48px desktop / 30px mobile page titles, 22px section titles and 16px prose, including legal pages. Blog articles use 32px medium titles, 22px medium section headings and the existing 18px Source Serif editorial recipe; headings and interface remain Switzer. Blog navigation uses 13px for Back to Blog and 12px for the desktop Contents rail. Legal subsection headings remain 18px. Marketing hero headlines can use the existing larger brand sizes. The shared Button adapter defaults to 32px; use size=public-cta for prominent public actions and the main controls in the sign-in, invite and Setup flows. Container width tokens describe content; the container recipe adds gutters. Prefer a few deliberate roles over new sizes for each component. The legacy interface retains its current tokens during coexistence.

Entry, recovery and Setup content share a 24px title and a 16px subtitle using the public body token, followed by an optional notice, fields and actions. Use 12px for footnotes beneath actions. The main sign-in hero keeps its lowercase, equal-scale title and muted tagline. Keep notices above the first field or action, with an alert role for errors and a status role for warnings and updates.

Use title case for Blog headlines and article titles, and keep the brand name noticed lowercase.

## Colors

Subtle warmth across public and signed-in pages: warm off-white with white cards in light mode, warm near-black with charcoal cards in dark mode. Keep noticed greens and red for destructive actions.

Canvas, raised groups and borders use --background, --card and --border. Global pages and foundation.module.css resolve these roles to the same --surface-*-light/dark palette in shared-styles.css; existing Tailwind classes such as bg-background, bg-card and border-border reuse these tokens inside and outside WebScope. Use the existing noticed brand identity and voice from /brand. Keep action emphasis neutral by default, green meaningful, and destructive entry points quiet; use filled red for destructive confirmation. Preserve readable contrast in both themes, including dark text on the approved dark-mode red button. Decorative background glow is outside this foundation.

The homepage, public frames, entry and Setup flows, app pages and global web UI share this palette. Read exact values from the shared surface tokens rather than copying color literals into components. Keep text, brand greens, semantic colors and imagery unchanged; white QR areas and artwork retain their intended colors.

## Controls

32px app buttons. Sign-in, invite, and Setup actions use 44px, as do prominent public calls to action. Soft rectangular corners, rounded inputs and grouped cards. Chips stay 20px high, including clickable chips.

Buttons use 16px radius with corner-shape: superellipse(2), not ordinary pill rounding. Inputs use ordinary 8px corners; grouped cards use 24px with superellipse(2). Use the same raised, bordered group recipe for Settings groups and Network cards; do not introduce a competing card surface. Menu dividers are faint 1px lines that run to the inner edges. Dialogs use 32px with superellipse(2).

General chips have two fills: neutral for ordinary labels and pale green for emphasis.

Relationship colors are semantic exceptions: retain the four closeness colors and green/blue intentions. Not now uses faint neutral fill and muted text, while remaining actionable. Network tabs and filters share 13px type and are vertically centered. Active filters use a muted green fill and show all selected icons. Compact filters summarize extra selections with a count; their tooltip lists every value. Network and Settings reuse the same tab recipe: 13px text, 44px targets, darker selected text and a 2px underline, without a filled background. All relationships comes first, then Trusted people and Suggestions. Last interaction is the default order. Below 640px use cards with desktop filters inactive.

Clickable status chips are an allowed exception: retain the 20px visible height and use a 10px chevron when needed. Keep larger effective touch targets without enlarging the visible chip. Use consistent functional icons, including a people icon for Network filter ‘All’. Source icons describe import origin, not whether an account is active: Google combines Gmail, Calendar and Contacts; the envelope means an email address from another source; Phone includes WhatsApp.

On Network cards, the recency chip shows the date and channel of the last interaction, including after a merge. The List view shows all source channels.

## Header and navigation

Public headers align to the viewport edges with a quiet Sign in button. The shared footer uses a thin divider, three link groups and the theme switcher.

Settings uses horizontal tabs and explicit Save changes. Align app navigation with page content, with the wordmark left and account control far right. The 52px header switches below 640px from wordmark and icon/text links to the plain 32px n and text-only links. Align the mobile n with the page title’s left edge. Keep 12px between mobile page links. The 44px logo touch target provides the space before navigation; add no extra gap after it. Keep at least 44px link touch targets. Network search sits below Invite, full width, with the same 12px gaps as the Reach and Invite cards.

The public header uses the full wordmark across screen sizes, with 16px side gutters and a 32px Sign in button where applicable. Setup uses the same header action style for Sign out and keeps its split layout on desktop. The shared footer uses the page background and a thin divider. It groups links under Resources, Legal and Connect, with the theme switcher next to the wordmark.

## Interaction

Make navigation predictable and changes explicit. Reuse accessible patterns. Improve the system when real use reveals friction; simplify rather than accumulate variants.

Use established accessible primitives. Support keyboard focus, loading, empty, error, disabled and selected states; check desktop, mobile, light and dark together. Do not infer mobile behavior solely from a desktop reference.

Apply the current foundation consistently while actively looking for better defaults. Propose refinements with concrete page evidence. When a refinement is agreed, replace obsolete guidance and unnecessary variants in this shared source so the human and agent references stay aligned. This is a living hypothesis, not a final specification or an implementation plan.

## References

- [Brand Guidelines](/brand)
- [Agent reference](/design-system.md)
- [Luma reference](https://luma.com)
