Skip to content

Commit e14ed69

Browse files
committed
Add spotlight direction utility.
1 parent 60293ad commit e14ed69

9 files changed

Lines changed: 72 additions & 28 deletions

File tree

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

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,15 @@ A tone contains more than one background and text color. These samples all selec
121121

122122
Keep fill, border, and text from the same role when you need a ready-made combination. Each role's colors are designed as a set within the active theme. The direct `tone-fill`, `tone-border`, and `tone-text` classes use the tone color itself; they are useful for accents, but they are not the same as a complete surface or button treatment.
123123

124-
`spotlight` is for large areas such as feature bands, callouts, and showcase panels. It is a deep field lit softly from the top-left corner, 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">`.
124+
`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">`.
125+
126+
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:
127+
128+
```mdx
129+
<Panel tone="accent" variant="spotlight" class="spotlight-from-top-right">
130+
...
131+
</Panel>
132+
```
125133

126134
## Tone-colored text and clipped fills
127135

‎frontend/theme/studioSkinLight.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ function state(background: string, border: string, text: string) {
2121
}
2222

2323
function spotlight(lit: string, deep: string) {
24-
return `radial-gradient(circle at 8% 0%, #ffffff66 0%, transparent 38%), linear-gradient(135deg, ${lit} 0%, ${deep} 75%)`
24+
return {
25+
field: `linear-gradient(165deg, ${lit} 0%, ${deep} 75%)`,
26+
light: '#ffffff66',
27+
}
2528
}
2629

2730
function createLightTone(colors: LightToneColors): StudioTone {

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,14 +35,14 @@ nav:
3535
</Flex>
3636
<p class="wp-disclosure text-subtle">An illustrative product and workspace, built with PureStack.</p>
3737
</div>
38-
<Panel tone="accent" variant="surfaceAlt" class="wp-product-shot theme--dark p-0 rounded-lg w-full mx-auto" aria-label="Illustrative Waypoint project dashboard">
38+
<Panel tone="accent" variant="spotlight" class="wp-product-shot spotlight-from-top-right p-0 rounded-lg w-full mx-auto" aria-label="Illustrative Waypoint project dashboard">
3939
<Flex align="center" class="wp-product-chrome wp-micro text-subtle mb-0 bb-1 b-subtle">
4040
<Flex class="wp-window-dots" aria-hidden="true"><i class="tone--success tone-fill-button rounded-pill"></i><i class="tone--warning tone-fill-button rounded-pill"></i><i class="tone--neutral tone-fill-button rounded-pill"></i></Flex>
4141
<span>WAYPOINT / PROJECT VIEW</span>
4242
<span class="ml-auto">EXAMPLE</span>
4343
</Flex>
4444
<Grid columns="1" columnsMd="minmax(0, 1fr) 10.5rem" class="wp-product-grid">
45-
<Panel tone="neutral" variant="surface" class="wp-project-card theme--light rounded-lg">
45+
<Panel tone="neutral" variant="spotlight" class="wp-project-card theme--light rounded-lg">
4646
<Flex justify="between" class="wp-micro text-subtle mb-0"><span>ACTIVE INITIATIVE</span><span>Q4 / 2026</span></Flex>
4747
<Flex align="center" justify="between" wrap="true" class="wp-project-heading gap-2">
4848
<h2>Autumn launch</h2>
@@ -58,13 +58,13 @@ nav:
5858
</div>
5959
</Panel>
6060
<Grid columns="1" columnsSm="2" columnsMd="1" class="wp-side-stack">
61-
<Flex direction="column" class="wp-side-card tone-fill-surface tone-text-surface b-1 tone-border-surface rounded-lg position-relative p-4">
61+
<Flex direction="column" class="wp-side-card tone-fill-spotlight tone-text-surface-alt b-1 tone-border-surface rounded-lg position-relative p-4">
6262
<span class="wp-micro text-subtle mb-0">NEXT REVIEW</span>
6363
<strong>Friday</strong>
6464
<span class="wp-side-meta text-subtle mb-0">10:00 · Project check-in</span>
6565
<Icon name="lucide:arrow-up-right" class="wp-side-icon position-absolute" aria-hidden="true"/>
6666
</Flex>
67-
<Flex direction="column" class="wp-side-card tone--secondary tone-fill-surface tone-text-surface b-1 tone-border-surface rounded-lg position-relative p-4">
67+
<Flex direction="column" class="wp-side-card tone--secondary tone-fill-spotlight tone-text-surface-alt b-1 tone-border-surface rounded-lg position-relative p-4">
6868
<span class="wp-micro text-subtle mb-0">OPEN DECISION</span>
6969
<strong>Release date</strong>
7070
<span class="wp-side-meta text-subtle mb-0">Owner assigned</span>

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,40 @@ interface States {
1212
}
1313
type Preset = Record<string, States>
1414

15+
/**
16+
* Where the spotlight's light falls. The skin sets its color; the page picks
17+
* the point with a spotlight-from-* class, top-left by default.
18+
*/
19+
const SPOTLIGHT_FROM_VAR = '--ps-spotlight-from'
20+
const SPOTLIGHT_FROM = {
21+
'top-left': '8% 0%',
22+
top: '50% 0%',
23+
'top-right': '92% 0%',
24+
'bottom-left': '8% 100%',
25+
'bottom-right': '92% 100%',
26+
} as const
27+
1528
export function createPresets(
1629
styleBuilder: StyleBuilder,
1730
current: ThemePaletteCurrent,
1831
theme: ThemeName,
1932
) {
2033
createFills(current, styleBuilder, theme)
34+
createSpotlightOrigins(styleBuilder, theme)
2135
createBorders(current, styleBuilder, theme)
2236
createText(current, styleBuilder, theme)
2337
createTextBg(current, styleBuilder, theme)
2438
createInset(current, styleBuilder, theme)
2539
}
2640

41+
function createSpotlightOrigins(styleBuilder: StyleBuilder, theme: string) {
42+
for (const [name, position] of Object.entries(SPOTLIGHT_FROM)) {
43+
styleBuilder
44+
.select(`.spotlight-from-${name}`, theme)
45+
.set(SPOTLIGHT_FROM_VAR, position)
46+
}
47+
}
48+
2749
function createPreset(
2850
fills: Preset,
2951
styleBuilder: StyleBuilder,
@@ -164,7 +186,7 @@ function createFills(
164186
},
165187
'tone-fill-spotlight': {
166188
rest: {
167-
background: current.spotlight,
189+
background: `radial-gradient(circle at var(${SPOTLIGHT_FROM_VAR}, ${SPOTLIGHT_FROM['top-left']}), ${current.spotlight.light} 0%, transparent 46%), ${current.spotlight.field}`,
168190
},
169191
},
170192
'tone-fill-surface': {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ function createCurrentPalette(
116116
return {
117117
tone: tokens.tone,
118118
canvas: tokens.canvas,
119-
spotlight: tokens.spotlight,
119+
spotlight: { ...tokens.spotlight },
120120
canvascolor: tokens.canvascolor,
121121
overlay: tokens.overlay,
122122
surface: {

‎packages/ts-style/src/skins/standard/chrome.ts‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { hexToRgba } from '@purestack/ts-css'
22
import { clamp } from '@purestack/ts-util'
3+
import type { SpotlightTokens } from '../../themePalette'
34
import type { ToneScale } from './shared'
45

56
export type ChromeState = 'rest' | 'hover' | 'active' | 'disabled'
@@ -51,28 +52,26 @@ export type SpotlightColors = {
5152
}
5253

5354
/**
54-
* A deep field lit from one corner, for feature bands and showcase panels.
55+
* A deep field and a soft light, for feature bands and showcase panels.
5556
* Unlike surfaces it has no gloss, hotspot, or edge shading, so large areas
56-
* stay calm. The field runs from a lit edge down into the alternate surface.
57-
* Light comes from the button color when it is brighter than the surface, so
58-
* dark fields keep their hue, and from white on light fields.
57+
* stay calm. The field runs from a lit top edge down into the alternate
58+
* surface; tone-fill-spotlight places the light where the page asks. Light
59+
* comes from the button color when it is brighter than the surface, so dark
60+
* fields keep their hue, and from white on light fields.
5961
*/
6062
export function createSpotlight(
6163
{ surface, surfaceAlt, button }: SpotlightColors,
6264
options: ChromeOptions = {},
63-
) {
65+
): SpotlightTokens {
6466
const lighting = clamp(options.lighting ?? 0.72, 0, 1.5)
6567
const light = luminance(button) > luminance(surface) ? button : '#ffffff'
66-
return layered([
67-
radialAt('8% 0%', [
68-
[rgba(mix(light, '#ffffff', 0.4), 0.7 * lighting), '0%'],
69-
['transparent', '38%'],
70-
]),
71-
linear('135deg', [
68+
return {
69+
field: linear('165deg', [
7270
[mix(surface, light, 0.35), '0%'],
73-
[mix(surface, surfaceAlt, 0.3), '75%'],
71+
[mix(surface, surfaceAlt, 0.15), '75%'],
7472
]),
75-
])
73+
light: rgba(mix(light, '#ffffff', 0.4), 0.9 * lighting),
74+
}
7675
}
7776

7877
export function createChrome(

‎packages/ts-style/src/skins/standard/shared.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ export function createTone(
237237
spotlight:
238238
overrides.spotlight ??
239239
(isGhost
240-
? 'transparent'
240+
? { field: 'transparent', light: 'transparent' }
241241
: createSpotlight(
242242
{
243243
surface: colors.surface,

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

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,17 @@ interface InteractiveToneState {
4747
text: string
4848
}
4949

50+
/**
51+
* A calm field for feature bands and showcase panels, lit softly from one
52+
* point. The skin decides the colors; the page decides where the light falls.
53+
*/
54+
export interface SpotlightTokens {
55+
/** Background of the field, without the light. */
56+
field: string
57+
/** Color of the light at its brightest point. */
58+
light: string
59+
}
60+
5061
export interface SemanticToneTokens {
5162
tone: string
5263
surface: {
@@ -64,8 +75,7 @@ export interface SemanticToneTokens {
6475
focusRing: string
6576
}
6677
canvas: string
67-
/** Deep field lit from one corner, for feature bands and showcase panels. */
68-
spotlight: string
78+
spotlight: SpotlightTokens
6979
canvascolor: string
7080
root: {
7181
border: {
@@ -134,8 +144,7 @@ export interface ThemeRadii {
134144
export interface ThemePaletteCurrent {
135145
tone: string
136146
canvas: string
137-
/** Deep field lit from one corner, for feature bands and showcase panels. */
138-
spotlight: string
147+
spotlight: SpotlightTokens
139148
canvascolor: string
140149
overlay: string
141150
surface: {

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

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ const CURRENT_INTERACTIVE_STATES = [
2424
const INTERACTIVE_PROPS = ['background', 'bgcolor', 'border', 'text'] as const
2525
const BORDER_PROPS = ['subtle', 'default', 'focus'] as const
2626
const TEXT_PROPS = ['default', 'subtle'] as const
27+
const SPOTLIGHT_PROPS = ['field', 'light'] as const
2728
const ICON_PROPS = ['background', 'gradient', 'color', 'border'] as const
2829
const EFFECT_PROPS = [
2930
'glowPrimary',
@@ -56,7 +57,7 @@ type InteractivePathTree<TStates extends readonly string[]> = {
5657
const CURRENT_THEME_PALETTE_PATHS = {
5758
tone: ['tone'],
5859
canvas: ['canvas'],
59-
spotlight: ['spotlight'],
60+
spotlight: createPropertyPathTree('spotlight', SPOTLIGHT_PROPS),
6061
canvascolor: ['canvascolor'],
6162
overlay: ['overlay'],
6263
surface: createInteractiveGroupPathTree(
@@ -357,7 +358,9 @@ function buildThemePaletteVarPaths() {
357358
for (const tone of SEMANTIC_TONE_NAMES) {
358359
paths.push(['semanticTone', tone, 'tone'])
359360
paths.push(['semanticTone', tone, 'canvas'])
360-
paths.push(['semanticTone', tone, 'spotlight'])
361+
for (const prop of SPOTLIGHT_PROPS) {
362+
paths.push(['semanticTone', tone, 'spotlight', prop])
363+
}
361364
paths.push(['semanticTone', tone, 'canvascolor'])
362365
paths.push(['semanticTone', tone, 'overlay'])
363366

0 commit comments

Comments
 (0)