Added Shade semantic tokens (#27109)

ref. https://linear.app/ghost/issue/DES-1329/semantic-tokens

- Made semantic tokens the only visual contract for shared UI in Shade,
so components are more consistent, more themeable, and easier for AI
agents to use correctly.

Author: peterzimon

apps/shade/src/components/features/color-picker/color-picker.tsx

@@ -62,7 +62,7 @@ export type ColorPickerProps = Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>
 
 export const ColorPickerRoot = ({
     value,
-    defaultValue = '#000000',
+    defaultValue = 'rgb(0 0 0)',
     onChange,
     className,
     ...props
@@ -245,10 +245,10 @@ export const ColorPickerHue = ({
             onValueChange={([value]) => setHue(value)}
             {...props}
         >
-            <Slider.Track className="relative my-0.5 h-3 w-full grow rounded-full bg-[linear-gradient(90deg,#FF0000,#FFFF00,#00FF00,#00FFFF,#0000FF,#FF00FF,#FF0000)]">
+            <Slider.Track className="relative my-0.5 h-3 w-full grow rounded-full bg-[linear-gradient(90deg,red,yellow,lime,aqua,blue,magenta,red)]">
                 <Slider.Range className="absolute h-full" />
             </Slider.Track>
-            <Slider.Thumb className="block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50" />
+            <Slider.Thumb className="block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:ring-1 focus-visible:ring-focus-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50" />
         </Slider.Root>
     );
 };
@@ -274,7 +274,7 @@ export const ColorPickerAlpha = ({
                 <div className="absolute inset-0 rounded-full bg-gradient-to-r from-transparent to-black/50 dark:to-white/50" />
                 <Slider.Range className="absolute h-full rounded-full bg-transparent" />
             </Slider.Track>
-            <Slider.Thumb className="block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50" />
+            <Slider.Thumb className="block size-4 rounded-full border border-primary/50 bg-background shadow transition-colors focus-visible:ring-1 focus-visible:ring-focus-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50" />
         </Slider.Root>
     );
 };

apps/shade/src/components/features/post-share-modal/post-share-modal.tsx

@@ -64,7 +64,7 @@ const PostShareModal: React.FC<PostShareModalProps> = (
                 </div>
                 <DialogHeader className='relative -mt-5'>
                     <DialogTitle className='text-3xl leading-[1.15em] font-bold'>
-                        <span className='text-green-500'>{primaryTitle}</span><br />
+                        <span className='text-state-success'>{primaryTitle}</span><br />
                         <span>{secondaryTitle}</span>
                     </DialogTitle>
                     {description &&
@@ -104,16 +104,16 @@ const PostShareModal: React.FC<PostShareModalProps> = (
                         :
                         <>
                             <div className='flex items-center gap-2'>
-                                <a aria-label='Share on X' className='flex h-[34px] w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://twitter.com/intent/tweet?text=${encodedPostTitle}%0A${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
+                                <a aria-label='Share on X' className='flex h-(--control-height) w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://twitter.com/intent/tweet?text=${encodedPostTitle}%0A${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
                                     <svg aria-hidden="true" viewBox="0 0 24 24"><path className="social-x_svg__x" d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"></path></svg>
                                 </a>
-                                <a aria-label='Share on Threads' className='flex h-[34px] w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://threads.net/intent/post?text=${encodedPostURLTitle}`} rel="noopener noreferrer" target='_blank'>
+                                <a aria-label='Share on Threads' className='flex h-(--control-height) w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://threads.net/intent/post?text=${encodedPostURLTitle}`} rel="noopener noreferrer" target='_blank'>
                                     <svg fill="none" viewBox="0 0 18 18"><g clipPath="url(#social-threads_svg__clip0_351_18008)"><path d="M13.033 8.38a5.924 5.924 0 00-.223-.102c-.13-2.418-1.452-3.802-3.67-3.816h-.03c-1.327 0-2.43.566-3.11 1.597l1.22.837c.507-.77 1.304-.934 1.89-.934h.02c.73.004 1.282.217 1.639.63.26.302.433.72.519 1.245a9.334 9.334 0 00-2.097-.101c-2.109.121-3.465 1.351-3.374 3.06.047.868.478 1.614 1.216 2.1.624.413 1.428.614 2.263.568 1.103-.06 1.969-.48 2.572-1.25.459-.585.749-1.342.877-2.296.526.317.915.735 1.13 1.236.366.854.387 2.255-.756 3.398-1.003 1.002-2.207 1.435-4.028 1.448-2.02-.015-3.547-.663-4.54-1.925-.93-1.182-1.41-2.89-1.428-5.075.018-2.185.498-3.893 1.428-5.075.993-1.262 2.52-1.91 4.54-1.925 2.034.015 3.588.666 4.62 1.934.505.622.886 1.405 1.137 2.317l1.43-.382c-.305-1.122-.784-2.09-1.436-2.892C13.52 1.35 11.587.517 9.096.5h-.01C6.6.517 4.689 1.354 3.404 2.986 2.262 4.44 1.672 6.46 1.652 8.994v.012c.02 2.534.61 4.555 1.752 6.008C4.69 16.646 6.6 17.483 9.086 17.5h.01c2.21-.015 3.768-.594 5.051-1.876 1.68-1.678 1.629-3.78 1.075-5.07-.397-.927-1.154-1.678-2.189-2.175zm-3.816 3.587c-.924.052-1.884-.363-1.932-1.252-.035-.659.47-1.394 1.99-1.482a8.9 8.9 0 01.512-.014c.552 0 1.068.053 1.538.156-.175 2.187-1.203 2.542-2.108 2.592z" fill="#000"></path></g><defs><clipPath id="social-threads_svg__clip0_351_18008"><path d="M0 0h17v17H0z" fill="#fff" transform="translate(.5 .5)"></path></clipPath></defs></svg>
                                 </a>
-                                <a aria-label='Share on Facebook' className='flex h-[34px] w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://www.facebook.com/sharer/sharer.php?u=${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
+                                <a aria-label='Share on Facebook' className='flex h-(--control-height) w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://www.facebook.com/sharer/sharer.php?u=${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
                                     <svg fill="none" viewBox="0 0 40 40"><title>social-facebook</title><path className="social-facebook_svg__fb" d="M20 40.004c11.046 0 20-8.955 20-20 0-11.046-8.954-20-20-20s-20 8.954-20 20c0 11.045 8.954 20 20 20z" fill="#1977f3"></path><path d="M27.785 25.785l.886-5.782h-5.546V16.25c0-1.58.773-3.125 3.26-3.125h2.522V8.204s-2.29-.39-4.477-.39c-4.568 0-7.555 2.767-7.555 7.781v4.408h-5.08v5.782h5.08v13.976a20.08 20.08 0 003.125.242c1.063 0 2.107-.085 3.125-.242V25.785h4.66z" fill="#fff"></path></svg>
                                 </a>
-                                <a aria-label='Share on LinkedIn' className='flex h-[34px] w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://www.linkedin.com/shareArticle?mini=true&title=${encodedPostTitle}&url=${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
+                                <a aria-label='Share on LinkedIn' className='flex h-(--control-height) w-14 items-center justify-center rounded-xs bg-muted px-3 hover:bg-muted-foreground/20 [&_svg]:h-4' href={`https://www.linkedin.com/shareArticle?mini=true&title=${encodedPostTitle}&url=${encodedPostURL}`} rel="noopener noreferrer" target='_blank'>
                                     <svg fill="none" viewBox="0 0 16 16"><g clipPath="url(#social-linkedin_svg__clip0_537_833)"><path className="social-linkedin_svg__linkedin" clipRule="evenodd" d="M1.778 16h12.444c.982 0 1.778-.796 1.778-1.778V1.778C16 .796 15.204 0 14.222 0H1.778C.796 0 0 .796 0 1.778v12.444C0 15.204.796 16 1.778 16z" fill="#007ebb" fillRule="evenodd"></path><path clipRule="evenodd" d="M13.778 13.778h-2.374V9.734c0-1.109-.421-1.729-1.299-1.729-.955 0-1.453.645-1.453 1.729v4.044H6.363V6.074h2.289v1.038s.688-1.273 2.322-1.273c1.634 0 2.804.997 2.804 3.061v4.878zM3.634 5.065c-.78 0-1.411-.636-1.411-1.421s.631-1.422 1.41-1.422c.78 0 1.411.637 1.411 1.422 0 .785-.631 1.421-1.41 1.421zm-1.182 8.713h2.386V6.074H2.452v7.704z" fill="#fff" fillRule="evenodd"></path></g><defs><clipPath id="social-linkedin_svg__clip0_537_833"><path d="M0 0h16v16H0z" fill="#fff"></path></clipPath></defs></svg>
                                 </a>
                             </div>

apps/shade/src/components/layout/list-header.tsx

@@ -16,7 +16,7 @@ type ListHeaderProps = PropsWithChildrenAndClassName & {
 function ListHeaderLeft({className, children}: PropsWithChildrenAndClassName) {
     return (
         <div
-            className={cn('flex min-w-0 flex-col gap-1 h-full min-h-[34px] justify-center', className)}
+            className={cn('flex min-w-0 flex-col gap-1 h-full min-h-(--control-height) justify-center', className)}
             data-list-header='list-header-left'
         >
             {children}

apps/shade/src/components/layout/view-header.stories.tsx

@@ -0,0 +1,65 @@
+import type {Meta, StoryObj} from '@storybook/react-vite';
+import {Button} from '@/components/ui/button';
+import {H1} from './heading';
+import {ViewHeader, ViewHeaderActions} from './view-header';
+
+const meta = {
+    title: 'Layout / View Header',
+    component: ViewHeader,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'fullscreen'
+    }
+} satisfies Meta<typeof ViewHeader>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    render: () => (
+        <ViewHeader>
+            <div>
+                <H1>Members</H1>
+                <p className='mt-2 text-sm text-text-secondary'>Manage your audience and member settings.</p>
+            </div>
+            <ViewHeaderActions>
+                <Button variant="outline">Export</Button>
+                <Button>Add member</Button>
+            </ViewHeaderActions>
+        </ViewHeader>
+    )
+};
+
+export const TitleOnly: Story = {
+    render: () => (
+        <ViewHeader>
+            <H1>Newsletter</H1>
+            <div />
+        </ViewHeader>
+    )
+};
+
+export const StickyPreview: Story = {
+    render: () => (
+        <div className="h-[520px] overflow-y-auto border border-border-default bg-surface-page px-8">
+            <ViewHeader className="bg-surface-page/90">
+                <div>
+                    <H1>Analytics</H1>
+                    <p className='mt-2 text-sm text-text-secondary'>Scroll this panel to verify sticky behavior.</p>
+                </div>
+                <ViewHeaderActions>
+                    <Button variant="outline">Filter</Button>
+                    <Button variant="secondary">Compare</Button>
+                    <Button>Export report</Button>
+                </ViewHeaderActions>
+            </ViewHeader>
+            <div className="space-y-3 py-8">
+                {Array.from({length: 18}, (_, index) => (
+                    <div key={index} className="rounded-md border border-border-default bg-surface-panel p-4 text-sm text-text-secondary">
+                        Placeholder content row {index + 1}
+                    </div>
+                ))}
+            </div>
+        </div>
+    )
+};

apps/shade/src/components/layout/view-header.tsx

@@ -20,8 +20,8 @@ const ViewHeader:React.FC<ViewHeaderProps> = ({className, children}) => {
     const [headerComponent, actionsComponent] = React.Children.toArray(children);
 
     return (
-        <header className='sticky top-0 z-50 -mx-8 bg-white/70 backdrop-blur-md dark:bg-black'>
-            <div className={cn('relative flex min-h-[102px] items-center justify-between gap-5 p-8 before:absolute before:inset-x-8 before:bottom-0 before:block before:border-b before:border-gray-200 before:content-[""] before:dark:border-gray-950', className)}>
+        <header className='sticky top-0 z-50 -mx-8 bg-surface-page/70 backdrop-blur-md'>
+            <div className={cn('relative flex min-h-[102px] items-center justify-between gap-5 p-8 before:absolute before:inset-x-8 before:bottom-0 before:block before:border-b before:border-border-default before:content-[""]', className)}>
                 {headerComponent}
                 {actionsComponent}
             </div>

apps/shade/src/components/ui/badge.tsx

@@ -4,7 +4,7 @@ import {cva, type VariantProps} from 'class-variance-authority';
 import {cn} from '@/lib/utils';
 
 const badgeVariants = cva(
-    'inline-flex items-center rounded-xs border px-1.5 text-xs font-semibold transition-colors focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:outline-hidden',
+    'inline-flex items-center rounded-xs border px-1.5 text-xs font-semibold transition-colors focus:ring-2 focus:ring-focus-ring focus:ring-offset-2 focus:outline-hidden',
     {
         variants: {
             variant: {

apps/shade/src/components/ui/banner.tsx

@@ -9,19 +9,19 @@ const bannerVariants = cva(
     {
         variants: {
             variant: {
-                default: 'border border-border bg-background shadow-sm hover:shadow-md dark:border-gray-900 dark:bg-gray-925',
+                default: 'border border-border-default bg-surface-panel shadow-sm hover:shadow-md',
                 gradient: [
-                    'cursor-pointer border border-gray-100 bg-white dark:border-gray-950 dark:bg-black',
+                    'cursor-pointer border border-border-subtle bg-surface-elevated',
                     'shadow-[-7px_-6px_42px_8px_rgb(75_225_226_/_28%),7px_6px_42px_8px_rgb(202_103_255_/_32%)]',
                     'dark:shadow-[-7px_-6px_42px_8px_rgb(75_225_226_/_36%),7px_6px_42px_8px_rgb(202_103_255_/_38%)]',
                     'hover:shadow-[-7px_-4px_42px_10px_rgb(75_225_226_/_38%),7px_8px_42px_10px_rgb(202_103_255_/_42%)]',
                     'dark:hover:shadow-[-7px_-4px_42px_10px_rgb(75_225_226_/_50%),7px_8px_42px_10px_rgb(202_103_255_/_52%)]',
                     'hover:translate-y-[-2px] hover:scale-[1.01]'
                 ],
-                info: 'border border-blue-200 bg-blue-50 dark:border-blue-800 dark:bg-blue-950/30',
-                success: 'border border-green-200 bg-green-50 dark:border-green-800 dark:bg-green-950/30',
-                warning: 'border border-yellow-200 bg-yellow-50 dark:border-yellow-800 dark:bg-yellow-950/30',
-                destructive: 'bg-white shadow-sm dark:bg-gray-950'
+                info: 'border border-state-info/40 bg-state-info/10',
+                success: 'border border-state-success/40 bg-state-success/10',
+                warning: 'border border-state-warning/40 bg-state-warning/10',
+                destructive: 'bg-surface-panel shadow-sm'
             },
             size: {
                 sm: 'p-2 text-sm',
@@ -87,7 +87,7 @@ const Banner = React.forwardRef<HTMLDivElement, BannerProps>(
                 {dismissible && (
                     <Button
                         aria-label="Dismiss notification"
-                        className="absolute top-1 right-1 size-8 text-gray-600 dark:text-gray-500 dark:hover:text-gray-300"
+                        className="absolute top-1 right-1 size-8 text-text-secondary hover:text-text-primary"
                         size="icon"
                         variant="ghost"
                         onClick={handleDismiss}

apps/shade/src/components/ui/breadcrumb.tsx

@@ -19,7 +19,7 @@ const BreadcrumbList = React.forwardRef<
     <ol
         ref={ref}
         className={cn(
-            'flex flex-wrap items-center gap-1.5 break-words text-sm font-medium text-muted-foreground sm:gap-2.5 h-[34px]',
+            'flex flex-wrap items-center gap-1.5 break-words text-sm font-medium text-muted-foreground sm:gap-2.5 h-(--control-height)',
             className
         )}
         {...props}

apps/shade/src/components/ui/button.tsx

@@ -6,20 +6,20 @@ import {ChevronDown} from 'lucide-react';
 import {cn} from '@/lib/utils';
 
 const buttonVariants = cva(
-    'inline-flex items-center justify-center gap-2 rounded-md text-sm whitespace-nowrap transition-colors focus-visible:ring-1 focus-visible:ring-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:stroke-[1.5px]',
+    'inline-flex items-center justify-center gap-2 rounded-md text-sm whitespace-nowrap transition-colors focus-visible:ring-1 focus-visible:ring-focus-ring focus-visible:outline-hidden disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:stroke-[1.5px]',
     {
         variants: {
             variant: {
                 default: 'bg-primary font-medium text-primary-foreground hover:bg-primary/90',
                 destructive: 'bg-destructive font-medium text-destructive-foreground hover:bg-destructive/90',
                 outline: 'border border-input bg-background font-medium hover:bg-accent hover:text-accent-foreground',
-                secondary: 'bg-secondary font-medium text-secondary-foreground hover:bg-secondary/80 dark:bg-gray-925/70 dark:hover:bg-gray-900',
+                secondary: 'bg-secondary font-medium text-secondary-foreground hover:bg-secondary/80',
                 ghost: 'font-medium hover:bg-accent hover:text-accent-foreground',
                 link: 'font-medium text-primary underline-offset-4 hover:underline',
                 dropdown: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground'
             },
             size: {
-                default: 'h-[34px] px-3 py-2',
+                default: 'h-(--control-height) px-3 py-2',
                 sm: 'h-7 rounded-md px-3 text-xs [&_svg]:size-3',
                 lg: 'h-11 rounded-md px-8 text-md font-semibold',
                 icon: 'size-9'

apps/shade/src/components/ui/card.tsx

@@ -185,9 +185,9 @@ interface KpiCardValueProps {
 const KpiCardHeaderValue: React.FC<KpiCardValueProps> = ({value, diffDirection, diffValue, diffTooltip}) => {
     const diffContainerClassName = cn(
         'flex items-center gap-1 text-xs h-[22px] px-1.5 rounded-xs group/diff cursor-default',
-        diffDirection === 'up' && `text-green-600 bg-green/10 ${diffTooltip && 'hover:bg-green/20'}`,
-        diffDirection === 'down' && `text-red-600 bg-red/10 ${diffTooltip && 'hover:bg-red/20'}`,
-        diffDirection === 'same' && 'text-gray-700 bg-muted'
+        diffDirection === 'up' && `text-state-success bg-state-success/10 ${diffTooltip && 'hover:bg-state-success/20'}`,
+        diffDirection === 'down' && `text-state-danger bg-state-danger/10 ${diffTooltip && 'hover:bg-state-danger/20'}`,
+        diffDirection === 'same' && 'text-text-secondary bg-muted'
     );
     return (
         <div className='relative flex flex-col items-start gap-2 lg:flex-row lg:gap-3'>