DC-172/DC-225: Extract shared design system into @sebt/design-system (2/4) (#98)

* DC-172: Add documentation, ADRs, skills, and repo cleanup

- Add ADRs for locale section filtering and rich-text rendering
- Add TDD design docs, implementation plans, and Figma comparison docs
- Add Claude Code skills (figma-verify, multi-repo-git, review-prep, test)
- Remove tracked .idea/ files and update .gitignore with blanket .idea/ rule
- Update CLAUDE.md with locale generation and design system guidance

* DC-172: Extract shared design system into @sebt/design-system workspace package

- Create packages/design-system with shared UI components, layout, providers,
  i18n, design tokens, SASS theme, and content generation scripts
- Move components (Alert, Button, InputField, TextLink, Header, Footer,
  HelpSection, SkipNav, LanguageSelector) from Portal Web to design-system
- Move content CSVs, locale generation script, design token scripts, SASS,
  and state JSON configs to design-system
- Add RichText component wrapping markdown-to-jsx
- Refactor Portal Web imports from @/components to @sebt/design-system
- Configure pnpm workspace, transpilePackages, and webpack alias for shared React
- Add workspace package.json, tsconfig, vitest config, and test setup

* fix: broken import, next version mismatch, RichText safety comment

* fix: generate fonts.ts to caller's cwd so Next.js @/ alias resolves in CI

* fix: remove duplicate react/next from design-system devDeps to prevent dual-instance hook errors

* fix: restore design-system devDeps and add Turbopack resolveAlias for React deduplication

* fix: use production build for E2E tests to avoid Turbopack dev React duplication

* fix: split design-system barrel to resolve dual React instance in E2E builds

* fix: initialize i18next before I18nProvider renders to prevent SSR hang

* fix: run next start in subshell so pnpm commands stay in repo root

---------

Co-authored-by: James Blair <jblair@codeforamerica.org>
Co-authored-by: Anthony Bergen <anthonydbergen@gmail.com>

Author: 3 people

.github/workflows/playwright-e2e.yaml

@@ -81,6 +81,12 @@ jobs:
       - name: Install Chrome for Pa11y
         run: cd src/SEBT.Portal.Web && pnpm exec puppeteer browsers install chrome
 
+      - name: Build frontend for E2E
+        env:
+          STATE: dc
+          NEXT_PUBLIC_STATE: dc
+        run: ./.github/workflows/scripts/build-frontend.sh --production
+
       - name: Run Pa11y and Playwright E2E tests
         env:
           CI: true
@@ -92,9 +98,12 @@ jobs:
           JwtSettings__SecretKey: "ci-e2e-jwt-secret-at-least-32-characters-long"
           IdentifierHasher__SecretKey: "ci-e2e-identifier-hasher-key-32chars"
           Oidc__CompleteLoginSigningKey: "ci-e2e-oidc-signing-key-at-least-32-chars"
+          PluginAssemblyPaths__0: "plugins-dc"
           UseMockHouseholdData: "true"
         run: |
-          pnpm dev &
+          # Start API in dev mode + frontend from production build
+          pnpm api:dev &
+          (cd src/SEBT.Portal.Web && pnpm start) &
           echo "Waiting for server at http://localhost:3000..."
           for i in $(seq 1 90); do
             curl -sf --max-time 15 http://localhost:3000 > /dev/null && echo "Server ready" && break

.gitignore

@@ -482,6 +482,7 @@ packages/design-system/content/.copy-hash
 packages/design-system/design/tokens.css
 packages/design-system/design/fonts.ts
 packages/design-system/design/sass/_uswds-theme-*.scss
+!packages/design-system/design/sass/_uswds-theme-custom-styles.scss
 packages/design-system/design/sass/_uswds-settings.scss
 
 # JetBrains IDE configuration

packages/design-system/content/scripts/.gitkeep

@@ -41,7 +41,8 @@
  * - Variable interpolation: Preserves {state}, {year} placeholders for runtime
  */
 
-import '../../design/scripts/load-env.js';
+// load-env.js is portal-specific and not needed in the shared package.
+// The script does not use any process.env variables.
 import { createHash } from 'crypto';
 import {
   existsSync,
@@ -51,9 +52,23 @@ import {
   rmSync,
   writeFileSync,
 } from 'fs';
+import * as path from 'path';
 import { dirname, join, relative } from 'path';
 import { fileURLToPath } from 'url';
 
+// Parse CLI arguments
+const cliArgs = process.argv.slice(2)
+function getCliArg(name) {
+  const idx = cliArgs.indexOf(name)
+  return idx !== -1 ? cliArgs[idx + 1] : null
+}
+const csvDirOverride = getCliArg('--csv-dir')
+const outDirOverride = getCliArg('--out-dir')
+const tsOutOverride  = getCliArg('--ts-out')
+const appFilter      = getCliArg('--app')   // 'portal' | 'enrollment' | null (all)
+const sectionsFilter = getCliArg('--sections')  // comma-separated, e.g., 'S1,GLOBAL'
+const allowedSections = sectionsFilter ? sectionsFilter.split(',').map(s => s.trim()) : null
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const contentDir = join(__dirname, '..');
@@ -63,8 +78,12 @@ const rel = p => relative(rootDir, p);
 // Configuration
 const CONFIG = {
   // State CSV files directory (content/states/{state}.csv)
-  statesDir: join(contentDir, 'states'),
-  outputDir: join(contentDir, 'locales'),
+  statesDir: csvDirOverride
+    ? path.resolve(process.cwd(), csvDirOverride)
+    : join(contentDir, 'states'),
+  outputDir: outDirOverride
+    ? path.resolve(process.cwd(), outDirOverride)
+    : join(contentDir, 'locales'),
   hashFile: join(contentDir, '.copy-hash'),
   locales: {
     en: 'English',
@@ -312,6 +331,9 @@ function buildStateLocaleData(rows, state) {
     const parsed = parseContentKey(contentKey);
     if (!parsed) continue;
 
+    // Section-level filter: skip rows from sections not in the allowed list
+    if (allowedSections && !allowedSections.includes(parsed.section)) continue;
+
     const { namespace, key } = parsed;
 
     // English — don't overwrite a non-empty value with an empty one
@@ -474,6 +496,36 @@ function validateStateCompleteness(stateData, state) {
   return warnings;
 }
 
+// Which namespaces belong to which app.
+// 'all' = shared, included in every app's barrel file.
+const NAMESPACE_APP = {
+  common:                 'all',
+  landing:                'all',
+  disclaimer:             'all',
+  personalInfo:           'all',
+  confirmInfo:            'all',
+  result:                 'all',
+  // Portal-specific
+  login:                  'portal',
+  idProofing:             'portal',
+  optIn:                  'portal',
+  offBoarding:            'portal',
+  dashboard:              'portal',
+  edit:                   'portal',
+  editContactPreferences: 'portal',
+  editMailingAddress:     'portal',
+  stepUpDisclaimer:       'portal',
+  stepUpFailure:          'portal',
+  proto:                  'portal',
+}
+
+function isNamespaceForApp(namespace, app) {
+  if (!app) return true
+  // eslint-disable-next-line security/detect-object-injection -- namespace comes from JSON filenames, not user input
+  const mapped = NAMESPACE_APP[namespace] ?? 'all'
+  return mapped === 'all' || mapped === app
+}
+
 /**
  * Generate TypeScript resource file from locale directory
  *
@@ -484,7 +536,9 @@ function validateStateCompleteness(stateData, state) {
  * Output: src/lib/generated-locale-resources.ts
  */
 function generateResourceFile() {
-  const outputPath = join(rootDir, 'src', 'lib', 'generated-locale-resources.ts');
+  const outputPath = tsOutOverride
+    ? path.resolve(process.cwd(), tsOutOverride)
+    : join(rootDir, 'src', 'lib', 'generated-locale-resources.ts');
 
   if (!existsSync(CONFIG.outputDir)) {
     console.log(
@@ -525,7 +579,8 @@ function generateResourceFile() {
         .sort();
 
       for (const file of files) {
-        const namespace = file.replace('.json', '');
+        const namespace = file.replace('.json', '')
+        if (!isNamespaceForApp(namespace, appFilter)) continue
         // Sanitize namespace for use as a JS identifier (handle hyphens → camelCase)
         const safeNs = namespace.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
         const varName = `${lang}${state.toUpperCase()}${safeNs.charAt(0).toUpperCase()}${safeNs.slice(1)}`;

….Web/content/scripts/generate-locales.js …stem/content/scripts/generate-locales.jssrc/SEBT.Portal.Web/content/scripts/generate-locales.js renamed to packages/design-system/content/scripts/generate-locales.js src/SEBT.Portal.Web/content/scripts/generate-locales.js renamed to packages/design-system/content/scripts/generate-locales.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Tests for generate-locales.js --app, --out-dir, --ts-out CLI args.
+ * Run: node packages/design-system/content/scripts/generate-locales.test.js
+ */
+import { strict as assert } from 'assert'
+import { execFileSync } from 'child_process'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const script = join(__dirname, 'generate-locales.js')
+const tmpDir = join(__dirname, '__test_tmp__')
+
+function setup() {
+  rmSync(tmpDir, { recursive: true, force: true })
+  mkdirSync(join(tmpDir, 'states'), { recursive: true })
+  mkdirSync(join(tmpDir, 'locales'), { recursive: true })
+  mkdirSync(join(tmpDir, 'ts-out'), { recursive: true })
+
+  // Minimal fixture CSV with portal-only and shared content
+  const csv = [
+    'Content,English,Español',
+    'GLOBAL - Button Continue,Continue,Continuar',
+    'S1 - Landing Page - Title,Portal Landing,Portal Landing ES',
+    'S7 - Portal Dashboard - Heading,Dashboard,Panel',
+  ].join('\n')
+  writeFileSync(join(tmpDir, 'states', 'co.csv'), csv)
+}
+
+function teardown() {
+  rmSync(tmpDir, { recursive: true, force: true })
+}
+
+setup()
+
+// Test: --app portal includes landing and dashboard, generates to --out-dir and --ts-out
+execFileSync('node', [
+  script,
+  '--csv-dir', join(tmpDir, 'states'),
+  '--out-dir', join(tmpDir, 'locales'),
+  '--ts-out',  join(tmpDir, 'ts-out', 'portal-resources.ts'),
+  '--app',     'portal',
+], { stdio: 'inherit' })
+
+const portalContent = readFileSync(join(tmpDir, 'ts-out', 'portal-resources.ts'), 'utf8')
+assert.ok(portalContent.includes('landing'),   'portal barrel must include landing namespace')
+assert.ok(portalContent.includes('dashboard'), 'portal barrel must include dashboard namespace')
+assert.ok(portalContent.includes('common'),    'portal barrel must include common namespace')
+
+// Test: --app enrollment includes common but excludes dashboard
+execFileSync('node', [
+  script,
+  '--csv-dir', join(tmpDir, 'states'),
+  '--out-dir', join(tmpDir, 'locales'),
+  '--ts-out',  join(tmpDir, 'ts-out', 'enrollment-resources.ts'),
+  '--app',     'enrollment',
+], { stdio: 'inherit' })
+
+const enrollmentContent = readFileSync(join(tmpDir, 'ts-out', 'enrollment-resources.ts'), 'utf8')
+assert.ok(enrollmentContent.includes('common'),     'enrollment barrel must include common namespace')
+assert.ok(!enrollmentContent.includes('dashboard'), 'enrollment barrel must NOT include dashboard namespace')
+
+// Test: locale JSON was written to --out-dir (not to script's own directory)
+assert.ok(existsSync(join(tmpDir, 'locales', 'en', 'co', 'landing.json')), 'locale JSON must be written to --out-dir')
+
+console.log('✅ All generate-locales CLI arg tests passed')
+teardown()