Skip to content

Commit e8b0fc5

Browse files
committed
Add flat, flatAlt and flatSolid semantic tone variants.
1 parent e7c159d commit e8b0fc5

7 files changed

Lines changed: 109 additions & 60 deletions

File tree

‎frontend/purestack.studio/components/landing/landing-band/landing-band.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ Use backgrounds as decoration and keep meaningful image content in a normal imag
143143
</ApiProperty>
144144

145145
<ApiProperty anchor="landing-band-prop-variant" name="variant" valueType="RefOrValue&lt;ComponentVariant&gt;" defaultValue="surfaceAlt">
146-
<p>Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.</p>
146+
<p>Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.</p>
147147
</ApiProperty>
148148

149149
<ApiProperty anchor="landing-band-prop-variantMode" name="variantMode" valueType="RefOrValue&lt;ComponentVariantMode&gt;" defaultValue="stateless">

‎frontend/purestack.studio/components/layout/panel/panel.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ Panel does not add an action or an accessible label. Give content sections a hea
137137
</ApiProperty>
138138

139139
<ApiProperty anchor="panel-prop-variant" name="variant" valueType="RefOrValue&lt;ComponentVariant&gt;" defaultValue="surface">
140-
<p>Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.</p>
140+
<p>Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.</p>
141141
</ApiProperty>
142142

143143
<ApiProperty anchor="panel-prop-variantMode" name="variantMode" valueType="RefOrValue&lt;ComponentVariantMode&gt;" defaultValue="stateless">

‎frontend/purestack.studio/guides/semantic-tones.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,13 @@ Keep fill, border, and text from the same role when you need a ready-made combin
123123

124124
`spotlight` is for large areas such as feature bands, callouts, and showcase panels. It is a calm field with a soft light, without the gloss and edge shading of surfaces and buttons, so it stays calm at any size. It has no interaction states and pairs with the alternate surface border and text classes. Components accept it as `variant="spotlight"`, for example `<Panel tone="accent" variant="spotlight">`.
125125

126+
Keep spotlights rare: one or two per page, for the pieces a visitor should notice first. Most surfaces should be quiet. `tone-fill-surface-flat`, `tone-fill-surface-alt-flat`, and `tone-fill-button-flat` paint a role's single color without the gradient chrome, with the same `-hover`, `-active`, `-disabled`, and `-all` forms as the gradient fills. Components accept them as `variant="flat"`, `variant="flatAlt"`, and `variant="flatSolid"`:
127+
128+
```mdx
129+
<Panel tone="neutral" variant="flat">A quiet card</Panel>
130+
<BtnLink href="/guide/" variant="flatSolid">A flat button</BtnLink>
131+
```
132+
126133
The skin sets the field and the light color; the page decides where the light falls. It comes from the top left by default. Move it with `spotlight-from-top`, `spotlight-from-top-right`, `spotlight-from-bottom-left`, or `spotlight-from-bottom-right`, for example to keep it visible when a card covers that corner:
127134

128135
```mdx

‎packages/ts-components/src/standard/componentVariant.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ export type ComponentVariant =
88
| 'surfaceAlt'
99
| 'spotlight'
1010
| 'glass'
11+
| 'flat'
12+
| 'flatAlt'
13+
| 'flatSolid'
1114
| 'outlineFill'
1215
| 'outline'
1316
| 'subtle'
@@ -46,6 +49,11 @@ const STATELESS_COMPONENT_VARIANT_CLASSES: Record<ComponentVariant, string> = {
4649
'b-1 rounded-md tone-fill-spotlight tone-border-surface-alt tone-text-surface-alt',
4750
glass:
4851
'b-1 rounded-md tone-fill-glass tone-border-surface-alt tone-text-surface-alt',
52+
flat: 'b-1 rounded-md tone-fill-surface-flat tone-border-surface tone-text-surface',
53+
flatAlt:
54+
'b-1 rounded-md tone-fill-surface-alt-flat tone-border-surface-alt tone-text-surface-alt',
55+
flatSolid:
56+
'b-1 rounded-md tone-fill-button-flat tone-border-button tone-text-button',
4957
outlineFill: 'b-2 rounded-md tone-border-button tone-text',
5058
outline: 'b-2 rounded-md tone-text',
5159
subtle: 'b-0 rounded-md tone-text',
@@ -58,6 +66,11 @@ const STATELESS_COMPONENT_VARIANT_CLASSES: Record<ComponentVariant, string> = {
5866
}
5967

6068
const STATEFUL_COMPONENT_VARIANT_CLASSES = {
69+
flat: 'tone-fill-surface-flat-hover tone-fill-surface-flat-active tone-border-surface-hover tone-border-surface-active tone-text-surface-hover tone-text-surface-active',
70+
flatAlt:
71+
'tone-fill-surface-alt-flat-hover tone-fill-surface-alt-flat-active tone-border-surface-alt-hover tone-border-surface-alt-active tone-text-surface-alt-hover tone-text-surface-alt-active',
72+
flatSolid:
73+
'tone-fill-button-flat-hover tone-fill-button-flat-active tone-border-button-hover tone-border-button-active tone-text-button-hover tone-text-button-active',
6174
solid:
6275
'tone-fill-button-hover tone-fill-button-active tone-border-button-hover tone-border-button-active tone-text-button-hover tone-text-button-active',
6376
surface:

‎packages/ts-ssg/sample-content/index.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ nav:
4242
<span class="ml-auto">Example</span>
4343
</Flex>
4444
<Grid columns="1" columnsMd="minmax(0, 1fr) 10.5rem" alignItems="start" class="gap-3 p-4">
45-
<Panel tone="neutral" variant="spotlight" class="theme--light rounded-lg p-5">
45+
<Panel tone="neutral" variant="flat" class="theme--light rounded-lg p-5">
4646
<Flex justify="between" class="gap-3 text-eyebrow fs-xxxs fw-800 mb-0"><span>Active initiative</span><span>Q4 / 2026</span></Flex>
4747
<Flex align="center" justify="between" wrap="true" class="gap-2 mt-4">
4848
<h2 class="fs-h2 m-0">Autumn launch</h2>
@@ -140,7 +140,7 @@ nav:
140140
<p class="tone-text-surface-alt opacity-75 lh-7 mb-0">Share what moved, what needs a decision, and where the team goes next. The example workspace keeps the details close when someone wants to go deeper.</p>
141141
<BtnLink href="/workspace/" variant="link" icon="lucide:arrow-up-right" iconPosition="end" class="p-0 mt-6 fw-700">Explore the example workspace</BtnLink>
142142
</div>
143-
<Panel tone="neutral" variant="spotlight" class="theme--light rounded-lg p-6 rotate-1">
143+
<Panel tone="neutral" variant="flat" class="theme--light rounded-lg p-6 rotate-1">
144144
<Flex direction="column" directionSm="row" justify="between" class="gap-1 pb-4 bb-1 b-default text-eyebrow fs-xxxs fw-800 mb-0"><span>Week 06 / Autumn launch</span><span>Friday brief</span></Flex>
145145
<h3 class="mt-5 mb-1">A good week of progress.</h3>
146146
<p class="text-subtle fs-xxs mb-4">The design handoff is complete. The help center draft is ready for final review.</p>
@@ -162,21 +162,21 @@ nav:
162162
<p class="text-subtle mb-0">One visual language can carry a product story, a working preview, and the guide behind it.</p>
163163
</Grid>
164164
<Grid columns="1" columnsMd="3" class="gap-4">
165-
<BtnLink href="/platform/" tone="neutral" variant="spotlight" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
165+
<BtnLink href="/platform/" tone="neutral" variant="flat" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
166166
<Flex container="span" direction="column" class="gap-2">
167167
<span class="text-eyebrow tone-text fs-xxxs fw-800 mb-0">01 / The story</span>
168168
<strong class="fs-h2 mt-5">Platform</strong>
169169
<span class="text-subtle fs-xxs mb-0">Discover the workflow and how it supports a team.</span>
170170
</Flex>
171171
</BtnLink>
172-
<BtnLink href="/workspace/" tone="neutral" variant="spotlight" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
172+
<BtnLink href="/workspace/" tone="neutral" variant="flat" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
173173
<Flex container="span" direction="column" class="gap-2">
174174
<span class="text-eyebrow tone-text fs-xxxs fw-800 mb-0">02 / The product</span>
175175
<strong class="fs-h2 mt-5">Workspace</strong>
176176
<span class="text-subtle fs-xxs mb-0">Explore project status, charts, and decisions in context.</span>
177177
</Flex>
178178
</BtnLink>
179-
<BtnLink href="/guide/" tone="neutral" variant="spotlight" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
179+
<BtnLink href="/guide/" tone="neutral" variant="flat" icon="lucide:arrow-up-right" iconPosition="end" class="rounded-lg p-5 justify-between align-flex-start ws-normal text-start fw-400 b-tone-hover lift-2-hover box-shadow-floating-hover">
180180
<Flex container="span" direction="column" class="gap-2">
181181
<span class="text-eyebrow tone-text fs-xxxs fw-800 mb-0">03 / The foundation</span>
182182
<strong class="fs-h2 mt-5">Starter guide</strong>

‎packages/ts-ssg/sample-content/platform.mdx‎

Lines changed: 67 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -16,101 +16,115 @@ nav:
1616
title="A shared view of the work behind every outcome."
1717
subtitle="Waypoint is a fictional product built to show a complete PureStack site. Its workflow is simple: define the work, keep the story current, and make the next decision obvious."
1818
titleTag="h1"
19+
eyebrowClass="tone-text fs-xxxs fw-800"
1920
titleClass="fs-display"/>
2021

2122
## Three views, one conversation
2223

23-
<Grid columns="1" columnsMd="3">
24-
<FeatureCard
25-
title="Initiatives"
26-
summary="Connect a goal to milestones, owners, and a realistic target date."
27-
icon="lucide:target"
28-
tone="accent"/>
29-
<FeatureCard
30-
title="Updates"
31-
summary="Record a concise summary of progress, risks, and the help a team needs."
32-
icon="lucide:message-circle"
33-
tone="secondary"/>
34-
<FeatureCard
35-
title="Decisions"
36-
summary="Keep the question, context, owner, and outcome together for future readers."
37-
icon="lucide:git-branch"
38-
tone="neutral"/>
24+
<Grid columns="1" columnsMd="3" class="gap-4 mb-6">
25+
<Panel tone="neutral" variant="flat" class="rounded-lg p-5">
26+
<Flex direction="column" align="start" class="gap-3">
27+
<IconFrame name="lucide:target" tone="accent" size="lg"/>
28+
<h3 class="fs-h3 m-0">Initiatives</h3>
29+
<p class="text-subtle mb-0">Connect a goal to milestones, owners, and a realistic target date.</p>
30+
</Flex>
31+
</Panel>
32+
<Panel tone="neutral" variant="flat" class="rounded-lg p-5">
33+
<Flex direction="column" align="start" class="gap-3">
34+
<IconFrame name="lucide:message-circle" tone="secondary" size="lg"/>
35+
<h3 class="fs-h3 m-0">Updates</h3>
36+
<p class="text-subtle mb-0">Record a concise summary of progress, risks, and the help a team needs.</p>
37+
</Flex>
38+
</Panel>
39+
<Panel tone="neutral" variant="flat" class="rounded-lg p-5">
40+
<Flex direction="column" align="start" class="gap-3">
41+
<IconFrame name="lucide:git-branch" tone="info" size="lg"/>
42+
<h3 class="fs-h3 m-0">Decisions</h3>
43+
<p class="text-subtle mb-0">Keep the question, context, owner, and outcome together for future readers.</p>
44+
</Flex>
45+
</Panel>
3946
</Grid>
4047

4148
## Follow a project from start to finish
4249

43-
<Tabs ariaLabel="Waypoint workflow" tone="neutral" variant="surface" tabVariant="underline">
50+
<Tabs ariaLabel="Waypoint workflow" tone="neutral" variant="flat" tabVariant="underline" class="mb-6">
4451
<TabPane id="plan" label="Plan" icon="lucide:target">
45-
<Grid columns="1" columnsMd="2" alignItems="center">
52+
<Grid columns="1" columnsMd="2" alignItems="center" class="gap-5">
4653
<div>
47-
<h3>Agree on the destination.</h3>
48-
<p>Write the outcome in plain language. Add a small set of milestones and one accountable owner, so progress has a clear meaning.</p>
54+
<h3 class="mt-0">Agree on the destination.</h3>
55+
<p class="text-subtle mb-0">Write the outcome in plain language. Add a small set of milestones and one accountable owner, so progress has a clear meaning.</p>
4956
</div>
50-
<AlertBox title="Example milestone" tone="info">Customer onboarding is ready when the welcome flow, help content, and handoff owner are confirmed.</AlertBox>
57+
<AlertBox title="Example milestone" tone="info" variant="rail">Customer onboarding is ready when the welcome flow, help content, and handoff owner are confirmed.</AlertBox>
5158
</Grid>
5259
</TabPane>
5360
<TabPane id="update" label="Update" icon="lucide:message-circle">
54-
<Grid columns="1" columnsMd="2" alignItems="center">
61+
<Grid columns="1" columnsMd="2" alignItems="center" class="gap-5">
5562
<div>
56-
<h3>Keep the picture current.</h3>
57-
<p>Share what changed, what is blocked, and what happens next. Short updates give the whole team useful context without another status meeting.</p>
63+
<h3 class="mt-0">Keep the picture current.</h3>
64+
<p class="text-subtle mb-0">Share what changed, what is blocked, and what happens next. Short updates give the whole team useful context without another status meeting.</p>
5865
</div>
59-
<AlertBox title="Example update" tone="success">The help center draft is complete. The only open item is final review of the welcome email.</AlertBox>
66+
<AlertBox title="Example update" tone="success" variant="rail">The help center draft is complete. The only open item is final review of the welcome email.</AlertBox>
6067
</Grid>
6168
</TabPane>
6269
<TabPane id="decide" label="Decide" icon="lucide:git-branch">
63-
<Grid columns="1" columnsMd="2" alignItems="center">
70+
<Grid columns="1" columnsMd="2" alignItems="center" class="gap-5">
6471
<div>
65-
<h3>Make decisions visible.</h3>
66-
<p>Record the options, the person deciding, and the reason for the choice. The next teammate can pick up the work with confidence.</p>
72+
<h3 class="mt-0">Make decisions visible.</h3>
73+
<p class="text-subtle mb-0">Record the options, the person deciding, and the reason for the choice. The next teammate can pick up the work with confidence.</p>
6774
</div>
68-
<AlertBox title="Example decision" tone="warning">The launch owner will choose the release date after accessibility review closes.</AlertBox>
75+
<AlertBox title="Example decision" tone="warning" variant="rail">The launch owner will choose the release date after accessibility review closes.</AlertBox>
6976
</Grid>
7077
</TabPane>
7178
</Tabs>
7279

7380
## Designed around a team rhythm
7481

75-
<Grid columns="1" columnsMd="2" class="mb-6">
76-
<Panel tone="neutral" variant="surfaceAlt">
77-
<p class="text-eyebrow">Monday</p>
78-
<h3>Set the focus</h3>
79-
<p>Review milestones and choose the few actions that would move the initiative forward this week.</p>
80-
</Panel>
81-
<Panel tone="neutral" variant="surfaceAlt">
82-
<p class="text-eyebrow">Friday</p>
83-
<h3>Share the learning</h3>
84-
<p>Summarize the change, record open decisions, and give stakeholders a trustworthy view of progress.</p>
85-
</Panel>
82+
<Grid columns="1" columnsMd="2" class="gap-5 mb-6">
83+
<Flex direction="column" class="gap-1 py-2 pl-4 bl-2 tone--accent tone-border">
84+
<span class="text-eyebrow tone-text fs-xxxs fw-800 mb-0">Monday</span>
85+
<h3 class="fs-h3 m-0">Set the focus</h3>
86+
<p class="tone--neutral text-subtle mb-0">Review milestones and choose the few actions that would move the initiative forward this week.</p>
87+
</Flex>
88+
<Flex direction="column" class="gap-1 py-2 pl-4 bl-2 tone--accent tone-border">
89+
<span class="text-eyebrow tone-text fs-xxxs fw-800 mb-0">Friday</span>
90+
<h3 class="fs-h3 m-0">Share the learning</h3>
91+
<p class="tone--neutral text-subtle mb-0">Summarize the change, record open decisions, and give stakeholders a trustworthy view of progress.</p>
92+
</Flex>
8693
</Grid>
8794

8895
<ComparisonTable
8996
tone="neutral"
97+
variant="none"
98+
columnsLg="2"
99+
class="p-0 box-shadow-none tone-text-surface"
90100
eyebrow="A clearer operating habit"
91101
title="What a shared workspace changes"
92102
subtitle="The comparison describes the sample product story and shows how to build a structured comparison page."
93103
>
94-
<ComparisonColumn title="Scattered updates" summary="The story lives across messages and meetings." icon="lucide:message-circle" tone="neutral">
104+
<ComparisonColumn title="Scattered updates" summary="The story lives across messages and meetings." icon="lucide:message-circle" tone="neutral" variant="flat" class="rounded-lg p-5">
95105
<ComparisonFeature icon="lucide:circle-question-mark" tone="neutral">Ownership is difficult to find.</ComparisonFeature>
96106
<ComparisonFeature icon="lucide:circle-question-mark" tone="neutral">Status depends on who you ask.</ComparisonFeature>
97107
<ComparisonFeature icon="lucide:circle-question-mark" tone="neutral">Decisions lose their context.</ComparisonFeature>
98108
</ComparisonColumn>
99-
<ComparisonColumn title="Waypoint" summary="The team sees the same current picture." icon="lucide:compass" tone="accent" variant="surfaceAlt" badge="Example approach">
109+
<ComparisonColumn title="Waypoint" summary="The team sees the same current picture." icon="lucide:compass" tone="accent" variant="flat" badge="Example approach" class="theme--dark rounded-lg p-5">
100110
<ComparisonFeature icon="lucide:check" tone="accent">Every initiative has an owner.</ComparisonFeature>
101111
<ComparisonFeature icon="lucide:check" tone="accent">Updates connect to milestones.</ComparisonFeature>
102112
<ComparisonFeature icon="lucide:check" tone="accent">Decisions stay with the work.</ComparisonFeature>
103113
</ComparisonColumn>
104114
</ComparisonTable>
105115

106-
<CtaSection
107-
tone="accent"
108-
eyebrow="See it in context"
109-
title="Open the example workspace."
110-
subtitle="Explore a sample initiative with status, charts, decisions, and next steps."
111-
primaryLabel="View workspace"
112-
primaryHref="/workspace/"
113-
primaryIcon="lucide:arrow-right"
114-
secondaryLabel="Read the guide"
115-
secondaryHref="/guide/"
116-
secondaryIcon="lucide:book-open"/>
116+
<Panel tone="accent" variant="spotlight" class="theme--dark rounded-lg p-6">
117+
<Grid columns="1" columnsLg="minmax(0, 1fr) auto" alignItems="center" class="gap-5">
118+
<SectionHeader
119+
eyebrow="See it in context"
120+
title="Open the example workspace."
121+
subtitle="Explore a sample initiative with status, charts, decisions, and next steps."
122+
eyebrowClass="tone-text fs-xxxs fw-800"
123+
titleClass="fs-h2"
124+
subtitleClass="tone-text-surface-alt opacity-75 mb-0"/>
125+
<Flex wrap="true" class="gap-3">
126+
<BtnLink href="/workspace/" tone="accent" icon="lucide:arrow-right" iconPosition="end" class="px-5 py-3 gap-4 fw-700 box-shadow-accent lift-1-hover">View workspace</BtnLink>
127+
<BtnLink href="/guide/" variant="glass" icon="lucide:book-open" class="px-5 py-3 gap-3 fw-700 lift-1-hover">Read the guide</BtnLink>
128+
</Flex>
129+
</Grid>
130+
</Panel>

‎packages/ts-style/src/semanticPresets.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,16 @@ function spotlightLight(current: ThemePaletteCurrent, reach: string) {
4242
return `radial-gradient(circle at var(${SPOTLIGHT_FROM_VAR}, ${SPOTLIGHT_FROM['top-left']}), ${current.spotlight.light} 0%, transparent ${reach})`
4343
}
4444

45+
function flatFill(role: ThemePaletteCurrent['surface']): States {
46+
return {
47+
all: true,
48+
rest: { background: role.rest.bgcolor },
49+
hover: { background: role.hover.bgcolor },
50+
active: { background: role.active.bgcolor },
51+
disabled: { background: role.disabled.bgcolor },
52+
}
53+
}
54+
4555
function glass(current: ThemePaletteCurrent) {
4656
const veil = `color-mix(in srgb, ${current.spotlight.light} 45%, transparent)`
4757
return `${spotlightLight(current, '75%')}, linear-gradient(${veil}, ${veil})`
@@ -204,6 +214,11 @@ function createFills(
204214
rest: { background: glass(current) },
205215
hover: { background: glass(current) },
206216
},
217+
// Flat fills paint each role's single color, without the gradient
218+
// chrome, for the many quiet surfaces around a few spotlights.
219+
'tone-fill-surface-flat': flatFill(current.surface),
220+
'tone-fill-surface-alt-flat': flatFill(current.surfaceAlt),
221+
'tone-fill-button-flat': flatFill(current.button),
207222
'tone-fill-surface': {
208223
all: true,
209224
rest: {

0 commit comments

Comments
 (0)