Skip to content

improvement(docs): align docs UI with the platform emcn design system#4962

Merged
waleedlatif1 merged 2 commits into
stagingfrom
fix/docs-style
Jun 11, 2026
Merged

improvement(docs): align docs UI with the platform emcn design system#4962
waleedlatif1 merged 2 commits into
stagingfrom
fix/docs-style

Conversation

@waleedlatif1

Copy link
Copy Markdown
Collaborator

Summary

  • mirror the platform emcn design tokens (surfaces, borders, text, badges, shadows, scrollbar) into the docs app, light + dark
  • add docs-local chip components mirroring emcn chrome (Chip/ChipLink, ChipDropdown, emcn-style DropdownMenu) and migrate the navbar Get started CTA, language dropdown, theme toggle, search trigger, copy-page button, and page navigation onto them
  • load Season Sans (the platform UI font) and apply it to the chip chrome so controls match the main app typeface
  • restyle page-type badges (Tutorial/Guide/Reference/Concept) onto the emcn Badge status palette (--badge-*)
  • align API reference styling: method badges on the badge palette, type/header/required pills on ChipTag chrome, response status dropdown on the emcn menu chrome
  • tokenize content chrome (inline code, code blocks, tables, cards, steps, blockquotes, FAQ, sidebar, TOC, typography) and collapse ~40 duplicate dark-mode rules into flipping tokens
  • normalize radii to the platform scale (6px tags/badges, 8px chips/items/inputs, 12px menus) and alias the workflow-preview --wp-* palette to the platform tokens so values can't drift
  • simplify the prev/next footer: single top hairline, rounded hover surfaces, no boxed-in dividers

Type of Change

  • Improvement

Testing

Tested manually — verified docs pages, API reference, and generated OpenAPI endpoint pages render in both themes; bun run lint and tsc --noEmit pass

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

@vercel

vercel Bot commented Jun 11, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview, Comment Jun 11, 2026 2:39am

Request Review

@cursor

cursor Bot commented Jun 11, 2026

Copy link
Copy Markdown

PR Summary

Low Risk
Presentation-only CSS and component styling in the docs app; no auth, API, or data-path changes. Main maintenance risk is keeping duplicated tokens in sync with apps/sim.

Overview
Aligns the docs app with the platform emcn design system so chip chrome, typography, and API pages match the main Sim app.

Tokens & global styling: Adds mirrored --surface-*, --text-*, --badge-*, and related CSS variables in global.css (light + dark), plus Season Sans via season.ts on the root layout. Replaces many duplicated html.dark color rules with single rules using those tokens across sidebar, TOC, prose, tables, code blocks, cards, and OpenAPI overrides. Workflow preview --wp-* variables now alias the shared tokens.

New chip UI: Introduces docs-local Chip / ChipLink, ChipDropdown, and restyled DropdownMenu. Navbar Get started uses ChipLink (brand); language picker uses ChipDropdown; search, theme toggle, copy-page, and prev/next arrows use chip geometry and token colors. Page-type badges move to the emcn badge palette with font-season.

Layout polish: Footer prev/next loses vertical dividers in favor of one top rule and rounded hover rows; navbar/search drop bespoke dark search-trigger overrides removed in favor of tokenized search styling.

Reviewed by Cursor Bugbot for commit a4db3f2. Configure here.

@greptile-apps

greptile-apps Bot commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR aligns the docs app visual chrome with the platform's emcn design system by mirroring CSS tokens, introducing local Chip/ChipDropdown components, loading Season Sans, and collapsing ~40 duplicate dark-mode rules into single token-flipping selectors.

  • New chip components (chip.tsx, chip-dropdown.tsx) replicate the emcn pill chrome using CVA variants and CSS custom properties; all existing controls (navbar CTA, language selector, theme toggle, search trigger, copy button, page arrows) are migrated onto them.
  • Token block in global.css mirrors --bg, --surface-*, --border-*, --text-*, --badge-*, and shadow variables from the platform globals so docs chip chrome renders identically — the wp-scope workflow-preview aliases are also updated to point at these shared tokens instead of duplicating raw values.
  • Design surface updates across badges, sidebar, footer, cards, steps, blockquotes, inline code, and code blocks replace hardcoded rgba/hex values with the new token references, with light/dark behavior handled entirely by the token flip in .dark.

Confidence Score: 5/5

Safe to merge — all changes are docs-app styling only, no functional logic or data paths are touched.

The PR is a pure design-system alignment across the docs app: new CSS custom properties, two new UI components (Chip/ChipDropdown), and token-reference updates across existing components. No business logic, data fetching, auth, or shared library code is changed. The global.css token additions are deliberate and isolated to the docs app. Manual testing across both themes was confirmed by the author, and lint + type-check pass.

No files require special attention. The new chip components are self-contained and well-typed, and the global.css token block is the only global-scope change.

Important Files Changed

Filename Overview
apps/docs/components/ui/chip.tsx New docs-local chip component mirroring emcn chrome; CVA variants and forwardRef patterns are correct, inline/flex via fullWidth variant always ensures items-center has a flex context
apps/docs/components/ui/chip-dropdown.tsx New ChipDropdown using Radix DropdownMenu; forwardRef typed correctly to HTMLButtonElement, disabled prop redundantly set on both trigger and button (harmless), onSelect used correctly vs onClick
apps/docs/components/ui/dropdown-menu.tsx Extracted CONTENT_BASE_CLASSES constant, updated tokens to emcn vars; DropdownMenuItem changed from py-1.5 padding to fixed h-[30px], rounded-[5px]→rounded-lg, dropped font-medium — all intentional design alignment
apps/docs/app/global.css ~120 lines of emcn token definitions added to :root/.dark; collapsed ~40 duplicate dark-mode rules into single token-flipping rules; two :root blocks present (no property name collisions with fumadocs vars)
apps/docs/app/fonts/season.ts Registers Season Sans variable font via next/font/local with correct variable weight range 300-800 and --font-season CSS variable
apps/docs/components/ui/language-dropdown.tsx Migrated to ChipDropdown; languageOptions now built in render scope (fixing previous module-level JSX); sideOffset effectively changed 6→4 (now uses DropdownMenuContent default), minor visual difference
apps/docs/components/page-type-badge.tsx Badges migrated from bordered pills to filled background using badge token palette; border and rounded-full removed in favour of rounded-md; transition-colors on static span is harmless
apps/docs/components/docs-layout/sidebar-components.tsx All hardcoded light/dark hex values replaced with CSS token references; duplicate dark: selectors collapsed cleanly
apps/docs/components/docs-layout/page-footer.tsx Simplified footer: single top hairline, removed vertical divider between prev/next, rounded hover surfaces; color references tokenized
apps/docs/components/navbar/navbar.tsx Get started button replaced with ChipLink variant='brand'; nav tab colors now reference --text-* tokens instead of hardcoded neutral-* classes
apps/docs/components/docs-layout/page-navigation-arrows.tsx Arrow links simplified to 30px chip-height square buttons using token colors; border+padding approach replaced with fixed size
apps/docs/components/page-actions.tsx LLMCopyButton migrated from raw button to Chip component with leftIcon prop; logic unchanged
apps/docs/components/ui/search-trigger.tsx Search trigger restyled to 30px chip height with token colors and font-season; removed dark-mode override rules from global.css that previously handled this
apps/docs/components/ui/theme-toggle.tsx Theme toggle button shape changed from rounded-full to rounded-lg; explicit icon sizes added; token colors applied
apps/docs/app/[lang]/layout.tsx Season font variable added to html className; no other changes

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["global.css\n:root / .dark token blocks\n--bg, --surface-*, --border-*, --text-*, --badge-*"] --> B["chip.tsx\nchipVariants (CVA)\nChip / ChipLink / ChipChevronDown"]
    A --> C["chip-dropdown.tsx\nChipDropdown"]
    A --> D["dropdown-menu.tsx\nCONTENT_BASE_CLASSES\nDropdownMenuItem"]
    B --> E["navbar.tsx\nChipLink variant='brand'"]
    B --> F["page-actions.tsx\nChip + leftIcon"]
    C --> G["language-dropdown.tsx\nChipDropdown"]
    D --> C
    A --> H["page-type-badge.tsx\nbadge-* tokens"]
    A --> I["sidebar-components.tsx\nsurface-* / text-* tokens"]
    A --> J["page-footer.tsx\nborder / surface-3 tokens"]
    A --> K["search-trigger.tsx\nsurface-5 / border-1 / font-season"]
    A --> L["theme-toggle.tsx\nsurface-active / text-icon tokens"]
    M["season.ts\nnext/font/local\n--font-season var"] --> N["layout.tsx\nhtml className += season.variable"]
    N --> K
    N --> B
Loading

Reviews (2): Last reviewed commit: "improvement(docs): build language dropdo..." | Re-trigger Greptile

Comment thread apps/docs/app/global.css
Comment thread apps/docs/components/ui/language-dropdown.tsx Outdated
@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@greptile

@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@cursor review

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit a4db3f2. Configure here.

@waleedlatif1 waleedlatif1 merged commit aa39974 into staging Jun 11, 2026
10 checks passed
@waleedlatif1 waleedlatif1 deleted the fix/docs-style branch June 11, 2026 02:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant