@nysds/mcp-server 1.18.1 → 1.19.0

package/data/guides/frameworks/react.md

@@ -43,3 +43,73 @@ function App() {
 - String attributes work normally: `<nys-button label="Click me" />`
 - For event listeners, use `ref` and `addEventListener` — React's synthetic event system doesn't forward to custom elements
 - Boolean attributes should be set explicitly: `<nys-button disabled={true} />`
+
+## Using the stepper in React (multi-page pattern)
+
+`nys-stepper` requires careful state management in React. Two state variables are needed:
+
+- `currentStep` — the furthest step the user has reached (progress boundary). Maps to the `current` prop on `NysStep`.
+- `viewingStep` — which step's content is currently displayed. Maps to the `selected` prop on `NysStep`.
+
+**Always pass both `current` and `selected` explicitly from React state.** Without explicit `selected`, the stepper's internal fallback will override the user's sidebar navigation on every React re-render.
+
+**Event listening:** Use `onNysStepClick` on each `NysStep` (not on `NysStepper`). Always call `e.preventDefault()` to suppress `href`-based page navigation.
+
+**Do not use `href` for SPA routing.** Omit `href` and handle step changes entirely in React state.
+
+**Do not place `<NysStepper>` inside a `<form>` element.**
+
+```tsx
+import { useState } from 'react';
+import { NysStepper, NysStep, NysButton } from '@nysds/components/react';
+
+const STEPS = [
+  { label: 'Personal Info',   content: <PersonalInfoForm /> },
+  { label: 'Contact Details', content: <ContactForm /> },
+  { label: 'Review',          content: <ReviewForm /> },
+];
+
+export function MultiStepForm() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [viewingStep, setViewingStep] = useState(0);
+
+  function handleContinue() {
+    if (viewingStep < STEPS.length - 1) {
+      setCurrentStep(viewingStep + 1);
+      setViewingStep(viewingStep + 1);
+    }
+  }
+
+  return (
+    <div className="nys-grid-row">
+      <NysStepper label="Application" className="nys-grid-col-12 nys-desktop:nys-grid-col-3">
+        {STEPS.map((step, i) => (
+          <NysStep
+            key={i}
+            label={step.label}
+            current={i === currentStep}
+            selected={i === viewingStep}
+            onNysStepClick={(e) => { e.preventDefault(); setViewingStep(i); }}
+          />
+        ))}
+        <div slot="actions">
+          <NysButton label="Save & Exit" variant="outline" fullWidth />
+        </div>
+      </NysStepper>
+
+      <main className="nys-grid-col-12 nys-desktop:nys-grid-col-9">
+        {STEPS[viewingStep].content}
+        <div style={{ display: 'flex', gap: '8px', marginTop: '16px' }}>
+          {viewingStep > 0 && (
+            <NysButton label="Back" variant="outline"
+              onNysClick={() => setViewingStep((v) => v - 1)} />
+          )}
+          {viewingStep === currentStep && currentStep < STEPS.length - 1 && (
+            <NysButton label="Continue" onNysClick={handleContinue} />
+          )}
+        </div>
+      </main>
+    </div>
+  );
+}
+```

package/data/guides/themes.md

@@ -0,0 +1,61 @@
+# NYSDS Themes
+
+NYSDS supports 8 agency themes that remap the `--nys-color-theme-*` design tokens to agency-specific color palettes. The default theme (NY.gov blue) is active when no theme is explicitly set.
+
+## Available Themes
+
+| Theme ID | Name | Description | Primary Color |
+|----------|------|-------------|---------------|
+| `default` | Default (NY.gov) | Default NY.gov theme for general state sites | `#154973` |
+| `admin` | Administration | For administrative and regulatory agencies | `#a2350a` |
+| `business` | Business | For commerce and economic development agencies | `#084b52` |
+| `environment` | Environment | For environmental and conservation agencies | `#233f2b` |
+| `health` | Health | For health and human services agencies | `#43285d` |
+| `local` | Local Government | For local government entities | `#402217` |
+| `safety` | Public Safety | For public safety agencies | `#435d6e` |
+| `transportation` | Transportation | For DOT and transit authorities | `#0b5583` |
+
+## How to Apply a Theme
+
+### HTML attribute (recommended)
+
+Set the `data-nys-theme` attribute on a root element:
+
+```html
+<html data-nys-theme="admin">
+```
+
+### CSS class
+
+Apply a theme class to any element:
+
+```html
+<body class="nys-theme-admin">
+```
+
+### Scoped theming
+
+Apply a theme to a specific section of the page:
+
+```html
+<section data-nys-theme="health">
+  <!-- All NYSDS components inside will use the Health theme -->
+</section>
+```
+
+## What Themes Change
+
+Themes remap these CSS custom properties to the agency's color palette:
+
+- `--nys-color-theme` — primary theme color
+- `--nys-color-theme-strong` — darker variant
+- `--nys-color-theme-stronger` — darkest variant
+- `--nys-color-theme-weak` — lighter variant
+- `--nys-color-theme-weaker` — lightest variant
+- `--nys-color-theme-weakest` — near-white variant
+
+All NYSDS components that use `--nys-color-theme-*` tokens automatically reflect the active theme.
+
+## Default Behavior
+
+The default theme applies at `:root` level. You do not need to set `data-nys-theme="default"` unless you are overriding a parent theme within a nested section.

package/data/tokens/tokens.css

@@ -1,5 +1,5 @@
 /*!
- * New York State Design System v1.18.1
+ * New York State Design System v1.19.0
  * Description: A design system for New York State's digital products.
  * Repository: https://github.com/its-hcd/nysds
  * License: MIT