[Yako-Ken]

• Initialize root monorepo workspace configuration and @asn/config-typescript.
• Scaffold apps/web with React 18, Vite, TypeScript, and Tailwind CSS.
• Download and configure local offline fonts (IBM Plex Sans Arabic and JetBrains Mono).
• Integrate provisional brand logo and favicon.
• Author complete design system specification in docs/architecture/design-system.md.
• Add structured documentation for all feature directories in apps/web/src/.

Changelog: docs/changelog/2026-10-24-web-scaffolding-and-design-system.md

Summary

Related issue

Change record

• Change record(s):
• Commit trailer(s): Changelog: docs/changelog/YYYY-MM-DD-slug.md

Type

• Feature
• Fix
• Docs
• Refactor
• Test
• Chore / CI / build
• Security
• Breaking change

Contracts and data

• No contract or persisted-schema change
• OpenAPI changed (link: )
• Event schema changed (link: )
• Migration added (owning service: )
• ADR required and linked (ADR: )
• Generated clients/types regenerated

Verification

• Commands:
• Results:
• Not run / not available:

Security and E2EE checklist

• No plaintext chat content, private keys, or recovery secrets in code, logs, events, tests, or fixtures
• Authorization is enforced server-side in the owning service
• No cross-database reads, joins, or transactions
• No secrets, tokens, real user data, or evidence payloads added
• The change does not weaken authentication, authorization, validation, or encryption

Risk and rollback

Reviewer notes

[HMH-3080]

Review — PR #1: Web client scaffolding and design system

Hi 👋 Thanks for the work. The foundation is solid, and I verified locally that the current branch installs and builds (npm ci, npm run build:web, tsc --noEmit) and that the documentation checks pass. The PR is not ready to merge yet: the Bun migration below is required, and the remaining issues are fixable. I have grouped them into: required decisions, required changes, code fixes, and follow-ups.

Before anything else, please rebase — the branch is one commit behind main (the Elixir/PostgreSQL scaffold), and that commit adds documentation files this PR must update.

git remote add upstream https://github.com/DevHustlers-Community/ASN.git
git fetch upstream
git rebase upstream/main
git push --force-with-lease origin feature/web-client-scaffolding-and-design-system

After rebasing, run:

bun install --frozen-lockfile
bun run typecheck
bun run build:web
python3 scripts/ci/check-changelog.py --all
python3 scripts/ci/check-links.py

The GitHub Actions run for this PR is currently action_required because it comes from a fork. Ask a maintainer to approve the workflow after the rebase.

---

1) Required: standardize the TypeScript toolchain on Bun

Maintainer decision: this repository uses Bun for all TypeScript tooling, including apps/web. This is not a preference for this PR only; it removes the npm/Bun split and makes the repository consistent with the Bun direction already documented for the TypeScript services.

Please migrate this PR from npm to Bun before merge:

1.1 Remove the npm lockfile and generate the Bun lockfile

At the repository root:

rm -rf node_modules package-lock.json
bun install

Commit the generated Bun lockfile (bun.lock with current Bun; do not commit both bun.lock and bun.lockb). Do not commit node_modules.

Why: two lockfiles for the same workspace cause non-reproducible installs and CI drift. package-lock.json must not remain.

1.2 Pin the Bun version in one place and reuse it everywhere

Add the same exact version to:

• .tool-versions (so mise install installs it):

  bun <pinned-version>
  

• root package.json:

  {
    "packageManager": "bun@<pinned-version>"
  }

• the CI workflow (oven-sh/setup-bun), shown below.

Replace <pinned-version> with the current stable Bun version you standardize on. Do not leave it floating.

1.3 Update the workspace dependency

In apps/web/package.json, replace:

"@asn/config-typescript": "file:../../packages/config-typescript"

with:

"@asn/config-typescript": "workspace:*"

Why: workspace:* tells Bun to link the local workspace package, makes the relationship explicit, and avoids accidentally installing a nested copy.

1.4 Update root scripts to Bun

The current root scripts invoke npm. Replace them with Bun workspace filters:

{
  "packageManager": "bun@<pinned-version>",
  "scripts": {
    "dev": "bun run --filter '@asn/web' dev",
    "dev:web": "bun run --filter '@asn/web' dev",
    "build": "bun run --filter '@asn/web' build",
    "build:web": "bun run --filter '@asn/web' build",
    "typecheck": "bun run --filter '@asn/web' typecheck",
    "lint": "bun run --filter '@asn/web' lint",
    "test": "bun run --filter '@asn/web' test"
  }
}

Add the matching scripts to apps/web/package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "test": "vitest run"
  }
}

If you prefer Bun's own test runner, use bun test with happy-dom instead of Vitest. Either is acceptable, but pick one, document it, and make CI run it through Bun.

1.5 Update CI to Bun

Add a web workflow (or extend the existing workflow) using the same pinned Bun version:

name: Web

on:
  pull_request:

jobs:
  web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: <pinned-version>
      - run: bun install --frozen-lockfile
      - run: bun run typecheck
      - run: bun run lint
      - run: bun run test
      - run: bun run build:web

--frozen-lockfile is important: it fails if bun.lock is out of sync with package.json, instead of silently changing dependency resolution in CI.

1.6 Remove every npm reference

Update all of these from npm to Bun:

• apps/web/README.md — bun install, bun run dev, bun run build.
• AGENTS.md §7 — the JS/TS verification row must use bun install and bun run typecheck|lint|test.
• docs/development/getting-started.md — add Bun to prerequisites and use Bun commands for the web app.
• docs/development/local-environment.md — add the Bun version to the versions table.
• docs/changelog/2026-10-24-web-scaffolding-and-design-system.md — replace npm install / npm run build:web with the Bun commands actually run.
• The PR body — same.

Verify the migration with:

grep -rn "npm\|package-lock" --include='*.md' --include='*.json' --include='*.yml' . | grep -v node_modules

The only acceptable matches are historical changelog entries or unrelated text; there should be no active npm command or package-lock.json reference.

1.7 Verify Bun actually runs the build

Do not assume Vite works under Bun just because the package manager changed. Run:

rm -rf node_modules
bun install --frozen-lockfile
bun run build:web
bun run dev   # check that the Vite dev server starts on port 3000

If a script still resolves to a Node shebang, force Bun with bun --bun run <script> (or bunx --bun) and document that in the README. The goal is that a clean clone needs Bun, not Node.

---

2) Decisions that need an explicit owner ruling

2.1 The name “Tawasol / تواصل”

docs/GLOSSARY.md contains an explicit rule:

Product name: ASN (Arabian Social Network). No alternate product name is used in code, docs, UI, or file names.

The new name appears in:

• apps/web/index.html (title and description)
• apps/web/src/app/App.tsx
• apps/web/README.md
• docs/changelog/2026-10-24-web-scaffolding-and-design-system.md
• docs/architecture/design-system.md

There are two valid paths, but this needs an owner decision before implementation:

1. Recommended for this PR: use ASN everywhere in the files above, and treat “Tawasol” as a separate proposal.
2. If the name is intentional: add an ADR, update docs/GLOSSARY.md, and document ownership/licensing of the name and logo. The changelog currently calls the logo “provisional”; a provisional asset must not become the product name in the UI and documentation.

2.2 The design-system document says “Approved” without approval

docs/architecture/design-system.md declares Status: Approved, but this PR has not been approved and has no ADR. docs/decisions/README.md says every significant, hard-to-reverse decision gets a numbered ADR. The document itself makes hard-to-reverse decisions: theme axes, token names, fonts, RTL rules, spacing, and accessibility standards.

Please:

• change the status to Proposed until it is reviewed, and add an owner and date;
• add an ADR (for example, 0012-frontend-design-system-and-theming.md) with context, decision, consequences, and alternatives;
• link the document from docs/architecture/README.md (table and reading order) and from the ADR. Right now the document is orphaned: searching for design-system only finds the changelog line;
• note that docs/architecture/README.md says the folder describes the current design, while this document is a target specification. Either label it explicitly as target design or move it somewhere more appropriate.

2.3 Web E2EE and auth decisions are being made implicitly

• apps/web/README.md and features/chat/README.md claim E2EE for the web client, but ADR 0010 (Web E2EE parity policy) is still open in docs/decisions/README.md.
• features/auth/README.md specifies a token strategy (access tokens in memory, refresh tokens in HttpOnly cookies, PKCE), while architecture-and-schema.md §9 lists token/session strategy as an open decision.

Please either remove these specifics or label them as proposed and blocked on the relevant ADR. Do not let a documentation PR resolve a security-sensitive open decision silently. The same applies to “private keys live in secure storage” on the web: client storage is not decided yet.

---

3) Update the source-of-truth documentation

docs/README.md says:

No stale stack assumptions. When the stack changes, every affected document is updated or explicitly marked superseded.

After the rebase, these files will be wrong:

3.1 AGENTS.md

• §1: “There are no … TypeScript manifests yet” — no longer true. apps/web/package.json, the Bun lockfile, and packages/config-typescript now exist.
• §7: the JS/TS row must reflect the actual Bun commands and include the web app’s typecheck/build.
• Check any other statement that assumes web is not scaffolded.

3.2 docs/development/getting-started.md

• “Social, Moderation, web, admin, and mobile have no manifests yet” — web now has one.

• “Bun | not required yet” — no longer true.

• Add the web app to the run instructions:

  bun install
  bun run dev:web

• Update “What works today” and “What does not work yet”.

3.3 docs/development/local-environment.md

• Port 3000: “Reserved; no manifest” → “Vite dev server (apps/web)”.
• Add Bun to the versions table, sourced from .tool-versions.
• Keep the port number consistent with apps/web/vite.config.ts (currently 3000, which is correct).

3.4 packages/config-typescript

• README.md still says Status: not written yet, and lists bun.json and react-native.json that do not exist.
• package.json lists bun.json in files, but the file is missing.
• Either add the preset or remove it from files and document it as planned. If Bun is now the runtime, a bun.json preset is a reasonable addition, but do not reference a file that does not exist.
• Document that base.json and react.json are now present and used by apps/web.

3.5 apps/web/README.md

The previous version had Owns, Boundaries, Tests, and Status, which AGENTS.md §8 requires for an app README. The new version removed them. Restore them, for example:

**Owns:** browser UI state and non-sensitive client cache only.

**Boundaries:**
- Consumes REST under `/api/v1/` and the Chat WebSocket channel.
- Does not read another service's database, hold service credentials, or decide
  visibility/authorization on its own.
- Chat envelopes are opaque handles; the browser never sends plaintext message
  bodies to Chat.

**Tests:** unit and component tests next to the feature; end-to-end flows live in
`tests/end-to-end`.

**Status:** scaffolded; no product routes or API integration yet.

The directory layout currently presents lib/api/, lib/websocket/, lib/auth/, Dialog, and Tabs as if there were implemented. Split the layout into Current and Planned, and do not write “built with” for anything that is not implemented.

3.6 Feature and utility READMEs

The thirteen feature READMEs describe complete features that do not exist, and some resolve open decisions:

• Add **Status:** planned — no implementation yet. to every feature README.
• features/auth/README.md: react-hook-form and zod are not installed. Either add them or mark the forms as planned.
• features/settings/README.md: “Who can message you — Everyone / Followers / Nobody” does not match chat_privacy_settings.allow_non_friend_messages, which is a boolean. Align with the schema or leave the product rule undecided.
• features/chat/README.md and the design document: chat_db.streaks is friendship-based in the architecture, not community streaks. Correct the attribution.
• app/README.md: the route list (/c/:slug, /u/:username, etc.) is a product proposal, not an existing contract. Mark it as proposed or remove it until the contracts exist.
• hooks/README.md and lib/README.md: list only what exists (cn), and mark the rest as planned.
• ChatBubble receipts: align with architecture-and-schema.md §3.11. Large channels use per-conversation last_read_seq; per-message receipts are reserved for direct chats or features that need them.

3.7 Design-system document consistency

Please fix these internal contradictions:

• tokens.css does not implement the documented light/dark status values. Add the light-theme overrides and use #ef4444 for destructive in dark mode, as documented.
• The document references --elevation-*, but tokens.css uses --bg-*. Rename one side.
• The scope lists packages/tokens, which does not exist. Remove it or add the package.
• The document says arbitrary values are rejected by CI, but there is no such lint, and the code contains text-[11px].
• The document claims a strict 4px grid, but the code uses 6px and 10px values (gap-1.5, px-2.5, w-2.5, w-3.5). Either allow half-steps and document them, or use the nearest 4px multiple.
• The document claims a 12px minimum font size, but input.tsx uses 11px.

---

4) Code fixes

4.1 Tailwind drops opacity modifiers on token colors

Utilities such as bg-primary/10, bg-status-success/10, and border-status-success/30 are not generated in the final CSS. I verified this in dist/assets/*.css: there is no primary\/10, status-success\/10, or primary\/30, while bg-white/90 works because it is a literal color.

As a result, the default Badge loses its background tint, the success box loses its tint, and the intended borders are missing.

Choose one fix:

Option A — explicit tint tokens (smaller change):

:root {
  --primary-surface: rgba(16, 185, 129, 0.10);
  --primary-border: rgba(16, 185, 129, 0.30);
  --status-success-surface: rgba(16, 185, 129, 0.10);
  --status-success-border: rgba(16, 185, 129, 0.30);
}

primary: {
  DEFAULT: 'var(--primary)',
  surface: 'var(--primary-surface)',
  border: 'var(--primary-border)',
}

Then use bg-primary-surface and border-primary-border instead of /10 and /30.

Option B — RGB channels (better long-term):

:root {
  --primary: 16 185 129;
}

primary: {
  DEFAULT: 'rgb(var(--primary) / <alpha-value>)',
}

This requires converting all tokens and theme overrides to RGB triplets. If that is too large for this PR, do Option A now and record Option B as a follow-up.

Verify after building:

bun run build:web
grep -F 'bg-primary\/10' apps/web/dist/assets/*.css

4.2 Accessibility: the claims do not match the implementation

The design document claims WCAG 2.1 AA, but:

• White on accent colors: emerald 2.54, amber 2.15, cyan 2.43, crimson 3.67, indigo 4.47 — all below 4.5 for 12–14px button text.
• --text-dim on cards is 3.87, and 4.35 on OLED.
• --status-destructive on cards is 3.87.
• text-[11px] in input.tsx violates the document’s own 12px floor.
• Presence and accent selection rely on color alone; there is no aria-pressed, and aria-label is attached to a plain <span>.
• The demo label is not associated with its input (htmlFor).

Please:

• add --primary-foreground per accent and use text-primary-foreground instead of text-white; verify every combination reaches 4.5:1 (use dark text on amber/cyan/emerald/crimson, and either dark text or a darker indigo);
• raise --text-dim in dark themes (for example, #9ca3af) until it reaches 4.5:1;
• use #ef4444 for destructive status in dark mode;
• replace text-[11px] with text-xs;
• add aria-pressed and accessible labels to the theme/accent buttons, plus a visible focus ring;
• add a hidden text label or icon for presence, and a proper role;
• use useId and htmlFor in Input/demo forms;
• add eslint-plugin-jsx-a11y through @asn/config-eslint.

4.3 Tests, lint, and CI

Currently there are no tests, lint is just tsc --noEmit, and there is no web CI job.

Add:

• a real typecheck script;
• ESLint and Prettier using @asn/config-eslint and @asn/config-formatting (currently README stubs);
• unit/component tests for cn, Button variants and isLoading, theme switching on document.documentElement, and Badge variants;
• the Bun CI workflow from section 1.5.

Do not add plaintext chat fixtures; the E2EE rules still apply.

4.4 Assets

• Convert the fonts (1.2MB of TTF) to WOFF2 with an Arabic/Latin subset, and preload the regular weight.
• Remove the duplicate logo: public/logo.png and src/assets/logo.png are identical (~196KB each).
• The logo has an opaque near-white background (254,254,254,255), which is why the header needs bg-white/90 on OLED. Provide a transparent or theme-aware variant, ideally SVG.
• 1024×559 is not a usable favicon. Add a square mark and 32/180/512 PNGs, plus apple-touch-icon.
• Add the OFL licenses for IBM Plex and JetBrains Mono under apps/web/public/fonts/ or apps/web/LICENSES/, and document the logo’s source and license.

4.5 Dependencies

• Remove or start using: zustand, lucide-react, react-router-dom, phoenix, @radix-ui/react-dialog, @radix-ui/react-dropdown-menu, @radix-ui/react-tabs.
• If phoenix stays, align it with the server’s Phoenix 1.8.16 rather than 1.7.14.
• React 18 / Vite 5 / Tailwind 3 are older than the current ecosystem in 2026. You do not have to upgrade in this PR, but record the rationale in the ADR instead of leaving it implicit.

4.6 Hygiene

• .gitignore: remove _legacy_archive/ and ASN-Design-System.md. They are unrelated to this PR, and globally ignoring a documentation filename is risky.
• The changelog uses py instead of python3; correct it and list the commands that actually ran.
• Fill in the PR template: Type, Contracts/Data, Verification, Security checklist, Risk/rollback.
• Add screenshots or a short GIF of the demo in OLED/Dim/Light and RTL, so the visual review is possible.
• If you split the PR into multiple commits, give each commit its own change record, as required by docs/changelog/README.md.

---

5) Final verification

rm -rf node_modules
bun install --frozen-lockfile
bun run typecheck
bun run lint
bun run test
bun run build:web
bun run dev   # confirm the dev server starts on port 3000

python3 scripts/ci/check-changelog.py --all
python3 scripts/ci/check-links.py

# Name check
grep -rn "Tawasol\|تواصل" apps docs AGENTS.md \
  --include='*.md' --include='*.ts' --include='*.tsx' --include='*.html'

# Stale documentation
grep -rn "no manifest\|not scaffolded\|not required yet" AGENTS.md docs apps

# No npm leftovers
grep -rn "npm\|package-lock" --include='*.md' --include='*.json' --include='*.yml' . \
  | grep -v node_modules

# Tailwind tint utilities
grep -F 'bg-primary\/10' apps/web/dist/assets/*.css

---

6) Acceptance checklist

• Branch rebased on main, CI approved and green.
• package-lock.json removed; bun.lock committed; packageManager and .tool-versions pin the same Bun version.
• Clean clone works with bun install --frozen-lockfile and bun run build:web; no Node-only assumption remains.
• All docs/commands use Bun; no npm references remain.
• CI uses oven-sh/setup-bun with the pinned version and --frozen-lockfile.
• Name decision resolved: ASN only, or ADR + glossary + name/logo ownership.
• ADR 0001 (monorepo/toolchain) and ADR 0012 (design system) exist, or the design document is Proposed and indexed.
• AGENTS.md, docs/development/*, and packages/config-typescript/README.md match the new reality.
• apps/web/README.md restores Owns/Boundaries/Tests/Status, with current vs planned separated.
• Feature READMEs are marked planned and do not resolve open auth/E2EE/privacy decisions.
• Tailwind tints and borders are present in dist.
• All small text meets 4.5:1; no 11px text; interactive controls have names and states.
• Tests, ESLint/Prettier, and web CI exist.
• WOFF2 fonts + OFL licenses; one logo + proper favicon sizes.
• Unused dependencies removed or justified.
• PR template completed, screenshots added, changelog verification accurate.

---

7) Closing note

This is a good foundation for the web client, and I do not want the work to be lost. If any of the owner decisions above are outside your scope, leave a TODO and ask for an explicit ruling instead of deciding implicitly — that matches AGENTS.md §10.

Happy to re-review after the Bun migration and the documentation updates. Thanks 🙏

[HMH-3080]

Hi @Yako-Ken,

Thanks again for the work on this PR. The Bun migration, the RGB token change, ADR 0012, the accessibility pass, the tests, and the new web CI are all solid, and I appreciate the care you put into the docs and the component structure. This is a strong foundation.

I pulled the latest head (b789ae0) and ran the full pipeline locally:

• bun install --frozen-lockfile ✅
• bun run typecheck ✅
• bun run test ✅ (10 tests, 16 expect() calls)
• bun run build:web ✅
• python3 scripts/ci/check-changelog.py --all and --range upstream/main..HEAD ✅
• python3 scripts/ci/check-links.py ✅
• Confirmed the alpha utilities are now generated: bg-primary/10, bg-status-success/15, border-status-success/30 ✅

The PR is close. Before we can accept it, please address the following final items.

Must fix before merge

1. Remove the old provisional logo.
   apps/web/public/logo.png is the old Tawasol asset (same file hash as the previous src/assets/logo.png), and index.html still links it as the PNG favicon. The new logo.svg is fine. Please delete/replace the old PNG with square ASN icons (32/180/512) and point apple-touch-icon at a 180×180 PNG.

2. Restore the documentation that was removed in b789ae0.
   docs/development/local-environment.md lost the env var table, .env setup, compose lifecycle, PGDATA note, manual inspection, and the broker DB restriction. docs/development/testing.md lost the production-DB warning, required failure paths, and E2EE test rules. Please restore those sections and reapply only the Bun additions. Also revert the 0009 row change in docs/decisions/README.md (or justify it in a separate ADR) and restore the status footer.

3. Re-encode and align the design-system doc.
   docs/architecture/design-system.md starts with a BOM and has mojibake such as Appendix A —, →, 1–4, ✓✓, and 🔒. Please save it as UTF-8 without BOM. While there, align it with tokens.css: #4f46e5/#e11d48, #9ca3af, the --*-rgb variables, --bg-* instead of --elevation-*, the light-theme status overrides, and a valid Appendix B (including the invalid --status-destructive: #ef4444 (dark) / #b91c1c (light); line). Also remove the "arbitrary values rejected by CI" claim unless we actually add that lint.

4. Fix the remaining contrast failures.
   The AA claim is not true yet in light/dim:

   • light status badges: 1.49–2.21:1
   • light success box: 1.39:1
   • light text-primary (links/default badge): 2.54:1
   • dark destructive button (white on #ef4444): 3.76:1
   • dim error text: 3.89:1
   • emerald/cyan hover: 4.02/3.64:1

   Please add per-theme status foreground tokens, replace the raw text-emerald-400/text-rose-400 etc. with semantic tokens, fix the hover/focus ring contrast, and add a visible label/icon for presence and accent selection. If we defer any of this, we must remove the WCAG AA claim and open a tracked issue — but the light-theme status components are visibly low-contrast, so I'd prefer to fix it now.

5. Correct apps/web/README.md.
   It says the app "uses opaque binary envelope fixtures (dev-opaque-v1)" — there are no fixtures and no chat implementation. It also lists Zustand (theme uses useState) and index.css (the file is globals.css). Please mark E2EE as planned, not implemented.

6. Make lint real, or stop calling it lint.
   "lint": "tsc --noEmit" is typechecking. Either add ESLint/Prettier (+ eslint-plugin-jsx-a11y) and wire it into web.yml, or rename the script to typecheck, remove the lint step from CI, and document the follow-up. The changelog's "bun run lint passed" is misleading as written.

7. Drop the .agents/skills/asn-senior-frontend addition from this PR.
   It uses token names that don't exist (bg-surface-oled, accent-emerald, rounded-radius-card), and its "never modify files outside the task directory" rule conflicts with AGENTS.md §6. A separate governance PR would be better.

8. Update the PR body and changelogs, and fix the commit subjects.
   The PR template is still empty (Summary, Change record, Type, Verification, Security, Risk). The remediation changelog says "Fixed WCAG AA" and "Resolved product naming" — both are not true yet. The Bun changelog has a Windows-only path/py command; please make it portable. Two commit subjects (1025546, b789ae0) start with U+FEFF; please strip the BOM during the rebase.

Follow-ups (please open issues)

• Remove or justify the unused dependencies: zustand, lucide-react, react-router-dom, phoenix (1.7.14 vs server 1.8.16), and the Radix dialog/dropdown/tabs packages.
• Convert the TTF fonts to WOFF2 (the OFL file is good).
• Strengthen the tests: Button isLoading, the real theme handler, and actual contrast assertions.
• Remove the remaining hardcoded palette colors / inline hex in the demo, or document the exception.

Once these are in and the Web and Governance workflows are green, I'll re-review for approval. The PR is currently MERGEABLE but UNSTABLE because the runs are action_required; I can approve the workflows after the next push.

Thanks again — I don't want this work to stall. Happy to help with a small follow-up commit if useful.

— HMH