Feat/midnight theme gradients integration

[jatinverma-prog]

📝 Description

Midnight Theme — Gradient Variants

Figma source: Outshift Spark Component Library

The gradient token layer

GradientVarsType (src/types/gradient-vars.ts) declares 46 tokens in three groups — fills, strokes, and radial glows — named from the gradient-token labels in Figma, camelCased from the Figma path (Gradient/Data-Viz-Cyan-Blue → gradientDataVizCyanBlue). It mirrors VarsType: one flat contract every theme implements, mounted on the MUI palette as palette.gradients, so components read theme.palette.gradients.* with no theme branching.

File	Role
src/types/gradient-vars.ts	The 46-token contract, with per-token provenance and rename notes
src/theme/style/gradient-vars-base.ts	Base/fallback map — the three shared gradients plus provisional mappings for the rest
src/theme/midnight/midnight-gradient-vars.ts	Midnight values, overriding 45 of 46 tokens
src/theme/style/color-palette.ts	midnightGradientStops — the raw stop colors the ramps are built from
src/theme/style/__tests__/gradient-vars.test.ts	22 tests asserting contract totality and Midnight coverage

Three gradients are shared by every theme, not diverged per theme, because design defined them once and the variants must look identical everywhere: gradientGlobalButtonPrimaryFill, gradientGlobalButtonPrimaryBorderGlow, and gradientTextWhiteBlue. Everything else in the base map is explicitly provisional, not design-approved — flagged in-file so it is not mistaken for a design deliverable. When design delivers Light / Dark / IoC ramps, each gets a *-gradient-vars.ts that spreads the base and overrides, exactly as Midnight does.

Where Figma's own labels were wrong or reused, the token carries the corrected name plus a comment recording the original (Data-Viz-Pink-Magenta whose stops are orange → gradientDataVizOrangeAmber; Card-Highlight-Radial which is actually linear; Panel-Exec-Border labelled radial but measured as a 135° diagonal ramp).

---

Components — gradient variants added

S.No.	Component	New API	Notes
1	Button	variant="gradient", variant="gradientOutlined"	Fill and border-glow ramps; shared across all themes
2	Card	glow, glass, alert, connector, image + CardAlertHeader	Five separate treatments, see below
3	Typography	variant="gradient"	background-clip: text on the white→blue ramp
4	Toast	glow	Global-Border/Fade border + blue cast; stronger when title is set
5	InputField	glow	Pill field edged with the Input-Border-Blue ramp, for prompt-style inputs
6	ActivityTimeline	variant="gradient", per-step time	The "Key Events" treatment
7	GaugeChart	gradient: "amber" | "teal" | "blue"	270° round-capped arc over a translucent track
8	SpiderChart	per-series gradient, stroke, dot	Four design-approved data-viz ramps

---

Structural changes

Button — Adds gradient and gradientOutlined variants reading gradientGlobalButtonPrimaryFill / gradientGlobalButtonPrimaryBorderGlow. The border-glow geometry was fitted to the rendered Figma node rather than copied from the swatch: the swatch is a horizontal rectangle but the button carries the ramp up its box, so the token is 7.5deg with stops at 10/90/170% — max channel error 3/255 against the render, versus 46 for a naive 90deg, 0/50/100.

Card — The largest surface change. Five independent treatments, each a boolean or scalar prop rather than a variant enum, so they compose:

• glass — Card-Glass-BG fill over a backdrop blur, white hairline, soft drop shadow. The fill is translucent, so the card picks up what is behind it.
• glow — gradient border plus blue glow. Mutually exclusive with image.
• alert="warning" | "critical" — translucent surface at the larger alert radius/padding; critical adds the rainbow gradient border, warning has none. CardAlertSeverity is deliberately not the Severity enum from @/common — that enum has no WARNING member and its other levels have no design in Alerts Card (274421:47415).
• connector — Graph-Connector fill and glow over a backdrop blur with a matching 1px gradient stroke, at a tighter 6px radius.
• image — photo layered over Welcome-Card-BG-Dark under an Overlay-Black-Fade-In scrim.

New CardAlertHeader (card-alert-header.tsx) picks up the parent card's accent color and takes an optional right-aligned timestamp.

Typography — Promoted from a bare MUI re-export to a local wrapper (src/components/typography/) so it can own the gradient variant. export { Typography } moves out of the MUI passthrough block in components/index.ts into export * from "./typography". Drop-in — the wrapper forwards all MUI Typography props — but it is a real change in what consumers import.

GaugeChart — The gradient treatment keeps both rings as recharts Pies so it shares a rendering path with the default gauge, but paints each sector through a custom renderGaugeArc: a filled sector cannot carry the frame's round cap (recharts approximates one from cornerRadius by trimming outer and inner edges by two different angles, joined by a straight edge). Stroke width is normalized to the frame's 171.7px gauge so it stays exact at any size, and the radius is derived from the box rather than lifted from Figma — the frame's own 84.18px radius plus half its stroke overflows its 171.7px bounds and would be clipped flat at 0°, 90° and 180°.

SpiderChart — New custom-gradient-radar.tsx shape. A series' gradient key sets background, stroke and dot together (ramp fills the area, its paired accent draws the outline, each vertex gets a ring in the same accent) unless those are passed explicitly. SpiderChartGradient is exported and documents its Figma-token ↔ theme-token mapping inline.

ActivityTimeline — variant="gradient" renders the "Key Events" style: glowing status dots on a single line that fades down the list, each step's time beside it. Steps run newest first, with the oldest two dimming to 50% and 30%.

Navigation — Not a gradient change. Drawer-item hover and selected were previously the same treatment; hover now adds the brandBackgroundPrimaryMedium fill but keeps the label on brandTextSecondary, and only selected paints brandTextPrimary — and holds that ramp while hovered.

---

Supporting (non-component) changes

Theme registration — light-theme.tsx, dark-theme.tsx, ioc-theme.tsx and midnight-theme.tsx each mount palette.gradients; src/types/theme.ts extends the palette type. baseGradientVars, midnightGradientVars and GradientVarsType are exported from the package root.

Storybook — New Foundations/Theme Gradients story renders every token as a labelled swatch, so the whole set is inspectable per theme in one place. welcome-card.jpg added for the Card image story.

Docs — card.md, button.md, toast.md, typography.md, gauge-chart.md, spider-chart.md, activity-timeline.md updated; new demo files for AlertCard, GlassCard, ConnectorCard, CardWithImage, ButtonIconOnlyGradient. colors.mdx and typography.mdx document the gradient layer.

Detailed rationale per token change lives in DESIGN-TOKEN-CHANGES.md.

---

Verification

Tests were not re-run in this session — the numbers below are the suite totals on this branch, not a fresh run. CI is the source of truth.

Suite	Tests in file	Covers
card.test.tsx	50	glass / glow / alert / connector / image + CardAlertHeader
activity-timeline.test.tsx	38	gradient variant, ordering, dimming, time
button.test.tsx	34	gradient and gradientOutlined
gradient-vars.test.ts	22	contract totality, Midnight coverage of all 46 tokens
toast.test.tsx	18	glow, glow-with-title
input-field.test.tsx	18	glow
spider-chart.test.tsx	15	per-series gradient, stroke, dot
gauge-chart.test.tsx	11	gradient arc geometry and ramps
navigation.test.tsx	10	hover vs selected split
typography.test.tsx	6	gradient text variant

Tests run with Node 22 (~/.nvm/versions/node/v22.23.1); the repo's default Node v20.9.0 is too old for the Vitest/Rolldown toolchain. This package's suite is Jest — npx jest --config=jest.config.js.

🔗 Related Issue

Closes #

🧪 Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Style/design update
• 🔧 Build/CI update
• ♻️ Refactoring (no functional changes)
• 🧪 Tests only

🧪 Testing

• Focused tests pass (yarn test --testPathPattern=)
• Lint and typecheck pass (yarn lint && yarn typecheck)
• Storybook builds successfully (yarn storybook:build)
• Manual testing completed
• Cross-browser testing (if applicable)

Test Instructions:

1. nvm use 22 && yarn install
2. yarn storybook and switch the theme to Midnight.
3. Open Foundations → Theme Gradients and confirm all 46 tokens render; switch to Light / Dark / IoC and confirm every swatch still paints (provisional fallbacks).
4. Check the new variants: Button (gradient, gradientOutlined), Card (Glow, Glass, CriticalAlert, WarningAlert, WithImage, connector), Toast (glow), InputField (glow), Typography (gradient), ActivityTimeline (gradient), GaugeChart (amber / teal / blue), SpiderChart (per-series ramps).
5. Navigation: hover an unselected drawer item — the fill appears but the label stays on the secondary ramp; only the selected item takes the primary ramp.
6. npx jest --config=jest.config.js in packages/open-ui-kit.

♿ Accessibility

• Follows WCAG 2.1 AA guidelines
• Keyboard navigation tested
• Screen reader tested
• Color contrast verified
• Focus indicators present
• ARIA attributes added where needed

📱 Responsive Design

• Mobile responsive
• Tablet responsive
• Desktop responsive
• All breakpoints tested

📚 Documentation

• Storybook story added/updated
• Component props documented
• Usage examples provided
• README updated (if needed)
• TypeScript types exported

🔄 Breaking Changes

• This PR introduces breaking changes
• Migration guide provided (if breaking changes)
• Version bump required

Typography is no longer the MUI re-export — it is now a local wrapper that forwards all MUI Typography props and adds the gradient variant. Expected to be drop-in, but it is a change in what @open-ui-kit exports under that name and is worth a reviewer's eye.

📋 Checklist

• Code follows the project's style guidelines
• Self-review of code completed
• Code is commented where necessary
• No console.log statements left in code
• Build passes locally
• Tests added for new functionality
• Existing tests still pass
• No TypeScript errors
• No accessibility violations
• Full unscoped yarn test was not run locally
• PR title follows conventional commit format

📸 Screenshots

Before

After

---

For Maintainers:

• Ready for review
• Requires design review
• Requires accessibility review
• Ready to merge