Add UI Non-Negotiables documentation and live style guide by timothyfroehlich · Pull Request #1093 · timothyfroehlich/PinPoint

timothyfroehlich · 2026-03-09T02:08:18Z

Summary

Establishes visual and structural consistency across PinPoint's UI by documenting non-negotiable patterns and providing a live, interactive style guide accessible at /debug/. This prevents component drift where developers invent their own card styles, heading sizes, or color choices.

Key Changes

New documentation: docs/UI_NON_NEGOTIABLES.md (557 lines)
- Comprehensive guide covering colors, layout, typography, cards, empty states, buttons, icons, loading states, badges, and glow effects
- 12 new rules (CORE-UI-005 through CORE-UI-017) extending existing CORE-UI-001..004
- Quick reference table and detailed patterns with do/don't examples
Live style guide at /debug/ with 7 interactive pages:
- /debug/colors — All CSS variable tokens with visual swatches
- /debug/typography — Heading hierarchy and section heading pattern
- /debug/components — Button variants/sizes, form inputs, alerts, destructive confirmations
- /debug/cards — The 5 canonical card variants with live examples
- /debug/states — Empty states, loading skeletons, error states
- /debug/badges — IssueBadge patterns for status/severity/priority/frequency
- /debug/layout — Page container, responsive breakpoints, grid patterns
Updated enforcement documentation:
- .claude/agents/pinpoint-reviewer.md — Added detailed UI pattern checks for CORE-UI-005 through CORE-UI-017
- docs/NON_NEGOTIABLES.md — Added summary rules for all new CORE-UI patterns
- .github/copilot-instructions.md — Added UI consistency checks
- AGENTS.md — Noted dual configuration requirement for Copilot reviews
- .claude/commands/check-non-negotiables.md — Updated to include UI pattern validation

Implementation Details

All style guide pages use the standard page container (max-w-6xl mx-auto py-10 space-y-6)
Live examples demonstrate correct patterns with accompanying code blocks
Each section includes the relevant rule number (CORE-UI-XXX) for easy reference
Style guide is dev-only (accessible at /debug/) and serves as the source of truth for visual consistency
Patterns are enforced through code review (pinpoint-reviewer agent) and the check-non-negotiables command

https://claude.ai/code/session_01DePhQsuE3KTUVgkdAcPBt3

Establishes visual consistency rules (CORE-UI-005..017) and a live style guide at /debug/ for reviewing UI patterns during PRs. ## What's new **docs/UI_NON_NEGOTIABLES.md** — 13 new rules covering: - Semantic color tokens only (CORE-UI-005) — no text-amber-500 etc. - Standard page container (CORE-UI-006) - Section heading override pattern (CORE-UI-007) - Card composition + 5 canonical variants (CORE-UI-008/009) - Empty state pattern (CORE-UI-010) - Button variants (CORE-UI-011) - AlertDialog for destructive actions (CORE-UI-012) - Lucide icons + standard sizes (CORE-UI-013) - Skeleton loading (CORE-UI-014) - IssueBadge for domain values (CORE-UI-015) - Glow effects (CORE-UI-016) - Mobile-first responsive patterns (CORE-UI-017) **Dev style guide pages** — live rendered reference at /debug/: - /debug/ — hub with links to all sections - /debug/colors — CSS token swatches - /debug/typography — heading hierarchy + text styles - /debug/components — button variants, inputs, alerts, AlertDialog - /debug/cards — 5 card variants + stat/empty patterns - /debug/states — empty state, skeleton, error patterns - /debug/layout — mobile vs desktop, breakpoints, grid patterns **Enforcement updates:** - docs/NON_NEGOTIABLES.md — added CORE-UI-005..017 with concise entries - .claude/agents/pinpoint-reviewer.md — full UI pattern section for Copilot and AI reviews (pattern + detection + anti-pattern + fix) - .claude/commands/check-non-negotiables.md — automated UI scan patterns **Drift fix:** badges/page.tsx heading colors changed from raw palette (text-amber-500, text-purple-500, text-cyan-500) to semantic tokens (text-warning, text-secondary, text-primary) https://claude.ai/code/session_01DePhQsuE3KTUVgkdAcPBt3

Adds CORE-UI-005..017 visual consistency rules to the GitHub Copilot review configuration and references the Copilot files from AGENTS.md so agents know to update them when adding new patterns. - .github/copilot-instructions.md: Added priority #10 "UI visual consistency" — semantic tokens, card variants, section headings, empty states, buttons, AlertDialog, icons, skeleton loading, domain badges, mobile-first grids - .github/instructions/components.instructions.md: Expanded DO/AVOID table with 8 new UI rows; fixed SeverityFilter example (was using raw <button> + string concat instead of <Button> + cn()); updated Styling Guidance with canonical rules; updated Common Mistakes section - AGENTS.md: Added note in GitHub Copilot Reviews section pointing to .github/ files as the other enforcement layer to keep in sync https://claude.ai/code/session_01DePhQsuE3KTUVgkdAcPBt3

vercel · 2026-03-09T02:08:23Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pin-point	Ready	Preview, Comment	Mar 9, 2026 2:08am

supabase · 2026-03-09T02:08:24Z

This pull request has been ignored for the connected project udhesuizjsgxfeotqybn due to reaching the limit of concurrent preview branches.
Go to Project Integrations Settings ↗︎ if you wish to update this limit.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

Copilot

Pull request overview

Adds a documented set of UI “non‑negotiable” patterns (CORE-UI-005..017) and a live /debug/* style guide to keep PinPoint UI visuals consistent and reduce component drift.

Changes:

Added docs/UI_NON_NEGOTIABLES.md with the extended UI ruleset and examples (CORE-UI-005..017).
Added multiple /debug/* pages under src/app/(app)/debug/ to render the canonical patterns (colors, typography, components, cards, states, layout).
Updated repo guidance/enforcement docs and instructions to incorporate the new UI consistency checks.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
src/app/(app)/debug/page.tsx	Adds `/debug` hub linking to each style guide section.
src/app/(app)/debug/colors/page.tsx	Live token swatches + glow utilities reference.
src/app/(app)/debug/typography/page.tsx	Documents heading hierarchy + section heading pattern.
src/app/(app)/debug/components/page.tsx	Interactive shadcn/ui component examples (buttons, inputs, dialogs, etc.).
src/app/(app)/debug/cards/page.tsx	Canonical card variants and examples (including stat/empty patterns).
src/app/(app)/debug/states/page.tsx	Empty/loading/error state patterns (Skeleton, empty cards).
src/app/(app)/debug/layout/page.tsx	Mobile-first breakpoints, grid patterns, spacing rhythm examples.
src/app/(app)/debug/badges/page.tsx	Updates badge debug headings to use semantic tokens (no raw palette colors).
docs/UI_NON_NEGOTIABLES.md	New primary documentation for UI rules CORE-UI-005..017.
docs/NON_NEGOTIABLES.md	Adds a summary of CORE-UI-005..017 and forbidden pattern list entries.
AGENTS.md	Notes Copilot review configuration must be updated in multiple instruction files.
.github/instructions/components.instructions.md	Expands component guidance with UI consistency rules + examples.
.github/copilot-instructions.md	Adds UI consistency checks to Copilot review priorities.
.claude/commands/check-non-negotiables.md	Extends the checklist to detect UI rule violations (palette colors, spinners, etc.).
.claude/agents/pinpoint-reviewer.md	Adds detailed UI visual consistency checks referencing the new docs and `/debug/*`.

Copilot · 2026-03-09T02:15:37Z

src/app/(app)/debug/typography/page.tsx

+
+export default function TypographyPage(): React.JSX.Element {
+  return (
+    <div className="max-w-6xl mx-auto py-10 space-y-10">


These debug style-guide pages are intended as the live reference for CORE-UI-006, but the outer page container uses space-y-10 instead of the documented standard space-y-6. Consider switching to space-y-6 here (and using larger spacing within sections if needed) so the reference page itself follows the non-negotiable container pattern.

Suggested change

<div className="max-w-6xl mx-auto py-10 space-y-10">

<div className="max-w-6xl mx-auto py-10 space-y-6">

Copilot · 2026-03-09T02:15:38Z

src/app/(app)/debug/components/page.tsx

+  const [switched, setSwitched] = useState(false);
+
+  return (
+    <div className="max-w-6xl mx-auto py-10 space-y-10">


The outer container uses space-y-10, but CORE-UI-006 documents the canonical authenticated page container as ... py-10 space-y-6. Since this is a style guide reference page, consider using the canonical container and placing any extra spacing inside sections.

Suggested change

<div className="max-w-6xl mx-auto py-10 space-y-10">

<div className="max-w-6xl mx-auto py-10 space-y-6">

Copilot · 2026-03-09T02:15:38Z

src/app/(app)/debug/cards/page.tsx

+        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+          <Card className="border-warning/30 bg-warning/10 glow-warning">
+            <CardHeader>


glow-warning is applied to a non-interactive card here, but CORE-UI-016 says glow is for interactive surfaces. Consider adding interactivity (Link/onClick + hover/cursor) or removing the glow from the static warning example so the style guide is self-consistent.

Copilot · 2026-03-09T02:15:38Z

src/app/(app)/debug/cards/page.tsx

+        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+          <Card className="border-success/30 bg-success/10 glow-success">
+            <CardHeader>


This example uses glow-success on a non-interactive card (no Link/onClick/cursor/hover). That conflicts with the CORE-UI-016 guidance elsewhere in this PR (“Only use glow on interactive surfaces”). Either make the example interactive (wrap in Link + add hover/cursor classes like Dashboard does) or remove the glow for the non-interactive variant.

Copilot · 2026-03-09T02:15:38Z

src/app/(app)/debug/layout/page.tsx

+
+export default function LayoutPage(): React.JSX.Element {
+  return (
+    <div className="max-w-6xl mx-auto py-10 space-y-10">


The style guide’s layout reference page uses space-y-10 on the outer container; CORE-UI-006 specifies space-y-6 for the standard page container. Updating this page to match the canonical container will keep the live reference self-consistent.

Suggested change

<div className="max-w-6xl mx-auto py-10 space-y-10">

<div className="max-w-6xl mx-auto py-10 space-y-6">

Copilot · 2026-03-09T02:15:40Z

docs/UI_NON_NEGOTIABLES.md

+
+Establishes visual and structural consistency across PinPoint's UI. These rules prevent component drift — where each developer invents their own card border style, section heading size, or empty state layout. Drift is invisible until you put two pages side by side.
+
+**Enforcement:** Code review (see `pinpoint-reviewer` agent), `check-non-negotiables` command, and the live style guide at `/debug/` (dev only).


This doc states the /debug style guide is “dev only”, but the current routing/middleware only makes /debug authenticated (not dev-only). Please either add an environment guard so /debug truly isn’t accessible in production, or remove/adjust the “dev only” wording throughout the docs so it matches reality.

Suggested change

**Enforcement:** Code review (see `pinpoint-reviewer` agent), `check-non-negotiables` command, and the live style guide at `/debug/` (dev only).

**Enforcement:** Code review (see `pinpoint-reviewer` agent), `check-non-negotiables` command, and the live authenticated style guide at `/debug/`.

Copilot · 2026-03-09T02:15:40Z

src/app/(app)/debug/states/page.tsx

+
+export default function StatesPage(): React.JSX.Element {
+  return (
+    <div className="max-w-6xl mx-auto py-10 space-y-10">


The outer page container uses space-y-10, but CORE-UI-006 documents the standard authenticated page container as max-w-6xl mx-auto py-10 space-y-6. Since these /debug pages are the reference, it’d be better if they adhere to the same container pattern.

Suggested change

<div className="max-w-6xl mx-auto py-10 space-y-10">

<div className="max-w-6xl mx-auto py-10 space-y-6">

Copilot · 2026-03-09T02:15:41Z

src/app/(app)/debug/cards/page.tsx

+
+export default function CardsPage(): React.JSX.Element {
+  return (
+    <div className="max-w-6xl mx-auto py-10 space-y-10">


This debug style-guide page uses space-y-10 on the page container, but CORE-UI-006 defines the canonical page container as max-w-6xl mx-auto py-10 space-y-6. Since this is meant to prevent drift, it should probably model the exact canonical container.

Suggested change

<div className="max-w-6xl mx-auto py-10 space-y-10">

<div className="max-w-6xl mx-auto py-10 space-y-6">

Copilot · 2026-03-09T02:15:41Z

src/app/(app)/debug/components/page.tsx

+"use client";
+
+import type React from "react";
+import { useState } from "react";
+import { Trash2, Plus, Settings, ChevronRight } from "lucide-react";


This whole page is marked "use client" just to support a couple interactive demos. To keep with the server-first pattern (and to reduce client bundle if /debug is reachable in prod), consider making the page a Server Component and extracting only the interactive examples (checkbox/switch state) into a small client component.

Copilot · 2026-03-09T02:15:41Z

src/app/(app)/debug/colors/page.tsx

+      <div
+        className={`size-10 rounded-lg border border-outline-variant shrink-0 ${className}`}
+      />


This uses template-literal class concatenation. Since CORE-UI-003 establishes cn() as the standard for class merging, consider switching to cn("...", className) here to avoid class ordering/merge issues and keep the style guide aligned with the repo convention.

claude added 2 commits March 8, 2026 17:59

Copilot AI review requested due to automatic review settings March 9, 2026 02:08

Copilot started reviewing on behalf of timothyfroehlich March 9, 2026 02:08 View session

Copilot AI reviewed Mar 9, 2026

View reviewed changes

	<div className="max-w-6xl mx-auto py-10 space-y-10">
	<div className="max-w-6xl mx-auto py-10 space-y-6">


		Establishes visual and structural consistency across PinPoint's UI. These rules prevent component drift — where each developer invents their own card border style, section heading size, or empty state layout. Drift is invisible until you put two pages side by side.

		Enforcement: Code review (see `pinpoint-reviewer` agent), `check-non-negotiables` command, and the live style guide at `/debug/` (dev only).

Conversation

timothyfroehlich commented Mar 9, 2026

Summary

Key Changes

Implementation Details

Uh oh!

vercel bot commented Mar 9, 2026

Uh oh!

supabase bot commented Mar 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants