利用AI Agent开发AI 新闻分析生产级项目（二）
·
prompts\design-system.md
# Prompt: App Design System (SKEW)
## Goal
Translate the attached SKEW design-system reference into the codebase as a real,
reusable foundation: design tokens, the Poppins type scale, and a small set of UI
primitives, plus a `/design-system` showcase page that mirrors the reference so the
tokens can be visually validated. This is the styling foundation later feature pages
(home cards, news details) will build on. Display-only; no app data, no pipeline logic.
## Skills read
- `AGENTS.md` — sections 1, 5 (architecture layers), 21 (standards), 22 (checks).
- No feature skill applies (clerk/supabase/oxylabs/ai-sdk are out of scope here).
Per AGENTS.md §3, Tailwind + shadcn-style patterns use existing project patterns
and package docs. Tailwind v4 `@theme` is the token mechanism.
## Existing code inspected
- `app/globals.css` — Tailwind v4 (`@import "tailwindcss"` + `@theme inline`), currently
only `--background`/`--foreground` and a dark `prefers-color-scheme` block. Font is
Arial fallback.
- `app/layout.tsx` — loads Geist / Geist_Mono via `next/font/google`; wires font vars.
- `app/page.tsx` — placeholder `<div>Home</div>`.
- `package.json` — Next 16.2.10, React 19, Tailwind v4. No clsx / tailwind-merge / cva.
- `tsconfig.json` — path alias `@/*` -> project root.
- No `components/` or `lib/` yet.
## Decisions / assumptions
- **Font:** Replace Geist with **Poppins** via `next/font/google` (weights 400/500/600/700
to cover Regular/Medium/SemiBold/Bold in the scale). Expose as `--font-sans`. Drop
Geist Mono (unused by the design). Body font-family becomes the Poppins variable.
- **Light-only:** The reference is a single light theme. Remove the `prefers-color-scheme:
dark` override so tokens are deterministic; keep `#FFFFFF` bg / `#0D0D0F` text.
- **cn helper:** add `clsx` + `tailwind-merge` and a `lib/utils.ts` `cn()` (standard
shadcn convention) so variant class merging is clean. Two tiny deps, not overbuild.
- **Components are lightweight, hand-rolled** with the tokens (no full shadcn CLI init —
that would scaffold config/registry we don't need yet). Variants via small maps.
- **Bias colors** map to semantic tokens: left `#B42318`, center `#E5E7EB`, right `#1D4ED8`.
- Showcase page lives at `app/design-system/page.tsx` — a dev/reference surface, static.
## Files likely to change / add
- `app/globals.css` — full `@theme` token set (colors, radius, shadow, type scale
vars); remove dark block; set Poppins body font. Add typography utility classes
(`.text-h1`…`.text-caption`) mapping size/weight/line-height from the reference.
- `app/layout.tsx` — Poppins font, updated `<html>` var, metadata title "SKEW".
- `lib/utils.ts` — `cn()`.
- `components/ui/button.tsx` — variants: primary, secondary, outline, text; states incl.
disabled; hover per reference.
- `components/ui/chip.tsx` — category chip with `+` affordance (and a plain variant).
- `components/ui/bias-meter.tsx` — left/center/right segmented meter with percentages
and 0/50/100 scale ticks; props `{ left, center, right }`.
- `components/ui/badge.tsx` — small label (sentiment / framing) used on cards.
- `components/ui/article-card.tsx` — the CARD EXAMPLE: image, category·country, title,
excerpt, bias meter, time-ago + read-time meta row, info + bookmark icons.
- `app/design-system/page.tsx` — showcase: brand, color swatches, type scale, buttons
grid, chips, bias meter, card example, spacing/grid/shadow/radius sections.
- `package.json` / lockfile — add `clsx`, `tailwind-merge`; add `typecheck` script
(`tsc --noEmit`) referenced by AGENTS.md §22 (currently missing).
## Token values (from reference)
- Colors: text-primary `#0D0D0F`, text-secondary `#6B7280`, surface `#F6F6F6`,
bg-primary `#FFFFFF`, bg-secondary `#F0F0F0`, border `#E5E7EB`, divider `#E5E7EB`,
bias-left `#B42318`, bias-center `#E5E7EB`, bias-right `#1D4ED8`, accent (text btn) `#1D4ED8`.
- Radius: sm 4px, md 8px, lg 12px, full 9999px.
- Shadow: sm `0 1px 2px rgba(0,0,0,.05)`, md `0 4px 12px rgba(0,0,0,.08)`,
lg `0 12px 24px rgba(0,0,0,.12)`.
- Type: H1 32/700/1.2, H2 24/600/1.3, H3 20/600/1.3, H4 16/500/1.4,
body-lg 16/400/1.6, body-md 14/400/1.6, body-sm 13/400/1.6, caption 11/400/1.4.
- Spacing: Tailwind's 4px base already matches (4/8/16/24/32/40/64 = 1/2/4/6/8/10/16).
- Grid: container max-width 1280px, 12 col, 24px gutter, 24px margin.
## Implementation requirements
- Preserve server/client boundaries: components are presentational; the showcase page is
a Server Component. Only add `"use client"` if an interaction genuinely needs it (none
expected — keep static).
- TypeScript, explicit prop types, no `any`. Small focused components.
- Use tokens (Tailwind classes generated from `@theme`), not hardcoded hex in components.
- Responsive: showcase and card must not overflow on mobile; card image `max-w-full`.
## Security requirements
- None touched (no secrets, no network, no browser-exposed server logic). Pure UI.
## Acceptance criteria
- `/design-system` renders every reference section with matching values.
- Poppins is the active font sitewide; type utilities match the scale.
- Buttons show primary/secondary/outline/text + disabled states with correct hover.
- Bias meter renders proportional left/center/right segments summing to 100 with labels.
- Article card matches the reference layout (image left, content right on desktop; stacked
on mobile).
- No dark-mode flip; deterministic light theme.
## Checks to run
- `npm run typecheck` (add script), `npm run lint`, and `npm run build` (new routes/config).
## Manual test steps
1. `npm run dev`.
2. Open `http://localhost:3000/design-system` — verify colors, type scale, buttons,
chips, bias meter, and the card example against the reference image.
3. Narrow the window to ~375px — confirm no horizontal overflow; card stacks.
4. Open `http://localhost:3000/` — confirm Poppins renders (home page can stay minimal
for now or show a simple branded placeholder).
这份 prompts/design-system.md 文件是 AI 助手按照 AGENTS.md 中规定的【强制工作流】生成的一份详细实施计划书。
在 AI 真正动手写代码之前，它必须把要做的事情写成这样一个文档，交给你审批。这份文档详细列出了如何为 SKEW 项目搭建底层 UI 设计系统。
下面为你逐个模块进行技术拆解：
1. Goal (目标) & Skills read (阅读的技能)
解释：
- 目标：把设计稿翻译成代码库里的基础组件（设计令牌、字体、基础 UI 零件），并做一个
/design-system的展示页面用来肉眼检查效果。强调这只是纯 UI 展示，不涉及任何业务数据或后端逻辑（不碰数据库、爬虫等）。 - 技能范围：按照规则，只读了
AGENTS.md，不涉及 Clerk/Supabase 等业务技能。因为项目用的是 Tailwind v4，所以使用 Tailwind v4 的@theme机制来管理设计令牌（Design Tokens）。
2. Existing code inspected (检查的现有代码)
解释：
AI 汇报了它“摸底”的情况：
- 看了
globals.css：发现目前只有基本的黑白颜色和深色模式，字体是兜底的 Arial。 - 看了
layout.tsx：目前加载的是 Geist 字体。 - 看了
package.json：确认了技术栈（Next 16.2.10, React 19, Tailwind v4），重点是发现项目里没有clsx和tailwind-merge（这两个是写 UI 组件必备的工具库）。 - 看了目录：发现还没有
components/和lib/文件夹。
3. Decisions / assumptions (关键决策与假设)
解释：
AI 根据摸底情况做出的技术选型和决定：
- 换字体：弃用 Geist，改用设计稿要求的 Poppins 字体（权重 400-700）。
- 砍掉深色模式：因为设计稿只有浅色主题，为了保证样式确定性，AI 决定移除现有的深色模式媒体查询。
- 加工具库：决定安装
clsx和tailwind-merge，并创建一个标准的cn()函数（这是 shadcn/ui 组件库的标准做法，用来优雅地合并 CSS 类名）。 - 手写轻量组件：不使用完整的 shadcn CLI 脚手架（避免过度构建），而是手写轻量级组件，用小 Map 管理样式变体。
- 偏见颜色定义：左倾（红
#B42318）、中立（灰#E5E7EB）、右倾（蓝#1D4ED8）。
4. Files likely to change / add (即将修改/新增的文件清单)
解释：
AI 列出了它准备动的所有文件，审批者可以一眼看出改动范围：
app/globals.css：写入全套设计令牌（颜色、圆角、阴影、排版工具类如.text-h1）。app/layout.tsx：换成 Poppins 字体。lib/utils.ts：新建，放cn()函数。components/ui/*.tsx：新建一系列基础 UI 组件（按钮、分类标签、偏见指标条、徽章、文章卡片）。app/design-system/page.tsx：新建展示页。package.json：增加依赖包，并补上一个typecheck脚本。
5. Token values (设计令牌具体数值)
解释：
这是 AI 从设计稿里提取的“绝对真理”，写死在文档里防止出错。所有组件都必须使用这些变量，而不能在代码里硬编码十六进制颜色。
- 涵盖了具体的颜色代码、圆角像素值（4/8/12px）、阴影参数、字号/字重/行高（比如 H1 是 32px/700粗细/1.2行高）。
- 间距采用 Tailwind 默认的 4px 基准制。
6. Implementation requirements (实现要求)
解释：
给代码质量定下的规矩：
- 服务端/客户端边界：展示页和组件默认保持为 Server Component（服务端组件），除非真的需要交互，否则绝对不乱加
"use client"。 - 强类型：必须用 TypeScript 明确定义 Props，禁止用
any。 - 响应式：在手机端（375px）不能出现横向滚动条，文章卡片图片要
max-w-full。
7. Security requirements (安全要求)
解释：
“None touched” —— 纯 UI 任务，不碰网络请求、不碰密钥、不碰服务端逻辑，没有任何安全风险。
8. Acceptance criteria (验收标准)
解释：
怎样才算任务完成？AI 列了几个硬性指标：
- 访问
/design-system能看到所有组件，且数值与设计稿一致。 - Poppins 字体全站生效。
- 按钮的各种状态（主次、禁用、悬停）正确。
- 偏见指标条：必须按比例渲染左/中/右三段，加起来等于 100%。
- 文章卡片在桌面端是图片左内容右，在手机端是上下堆叠。
9. Checks to run & Manual test steps (检查与测试步骤)
解释：
- 自动检查：写完后必须跑
npm run typecheck（类型检查）、npm run lint（代码规范）、npm run build（构建测试）。 - 手动测试：指导人类如何验收：1. 启动项目；2. 打开展示页对比设计稿；3. 把浏览器窗口缩到手机大小看会不会溢出；4. 看首页字体对不对。
总结
这份文件完美诠释了 AGENTS.md 所要求的“先写计划，后写代码”的工作流。AI 把抽象的“搭建设计系统”任务，拆解成了具体的文件路径、色号值、组件 Props 和测试步骤。如果你对这个文件里的任何一条不满意（比如“我不想要 Poppins，我想用思源黑体”），你可以在 AI 动手前让它修改这个计划文件，从而避免写出一堆要重写的代码。
prompts\home-page-ui.md
# Prompt: Home Page UI (SKEW)
## Goal
Build the SKEW **home page** at `app/page.tsx` to match the attached reference: a
utility top bar, a sticky site header with logo + primary nav + auth buttons, a
horizontally-scrollable category chip row, a "Top News" section, and a responsive
3-column grid of vertical news cards. Display-only. No scraping, no analysis, no
pipeline mutation, no live Supabase reads yet (data layer not built) — render from
typed mock data so the layout can be validated pixel-close now and swapped to real
Supabase queries later without touching the presentational components.
## Skills read
- `AGENTS.md` — §1 (build list: home page with news cards), §5 (architecture layers —
UI displays data only, no scrape/analyze/mutate), §19 (article-card required fields),
§21 (standards, server/client boundaries), §22 (checks).
- No feature skill applies (clerk/supabase/oxylabs/ai-sdk out of scope for pure UI).
Per §3, Tailwind/shadcn-style work uses existing project patterns + `@theme` tokens.
- `prompts/design-system.md` — the established token + primitive foundation this builds on.
## Existing code inspected
- `app/globals.css` — Tailwind v4 `@theme` tokens: colors (`text-primary`, `text-secondary`,
`surface`, `bg-primary`, `bg-secondary`, `border`, `divider`, `bias-left/center/right`,
`accent`), radius, shadow, `--container-app: 1280px`, and `.text-h1…caption` type utils.
- `app/layout.tsx` — Poppins via `next/font/google`, light-only, `<body class="min-h-full flex flex-col">`.
- `app/page.tsx` — current placeholder branded screen (to be replaced).
- `components/ui/` — `button.tsx` (primary/secondary/outline/text), `chip.tsx` (label + `addable` `+`),
`bias-meter.tsx` (`{left, center, right}`, optional `showScale`; labels "Left/Center/Right N%"),
`badge.tsx`, `article-card.tsx` (HORIZONTAL layout — not what the home grid uses).
- `lib/utils.ts` — `cn()`. `package.json` — Next 16.2.10, React 19, Tailwind v4, clsx + tailwind-merge.
## Decisions / assumptions
- **Vertical card, new component.** The reference cards are image-on-top / content-below,
unlike the existing horizontal `article-card`. Add `components/ui/news-card.tsx` rather than
overloading `article-card`. Keep `article-card` untouched (design-system still uses it).
- **Mock data, typed.** No Supabase yet, so add `lib/mock/news.ts` exporting a typed
`MOCK_ARTICLES` array shaped like the eventual query result (fields from §19: title, source,
country, image, category, publish info, sentiment/framing left/center/right, sources count).
When real queries land, only the page's data source changes — cards stay presentational.
- **Bias meter label format.** Reference shows the left segment as `L 20%` (short) while
center/right read `Center 31%` / `Right 49%`, and a very small left segment collapses to just
`10%`. Add an optional `variant="compact"` (or `shortLeftLabel`) to `bias-meter.tsx` so the
card uses the short `L` form without changing the design-system's existing full-label usage.
Segments below a width threshold show percentage only (no clipped word). Do NOT rewrite the
default behavior — extend it additively.
- **Header interactivity is presentational.** Theme toggle (Light/Dark/Auto), Set Location,
edition dropdown, Subscribe, and Login are static/visual only — Clerk is not wired yet and
the app is light-only per the design system. Login/Subscribe render as buttons with no auth
behavior (wired in the later Clerk task). Nav links point to `/` for now (only Home exists).
- **Server Components by default.** Page and cards are static Server Components. Add
`"use client"` ONLY to the smallest piece that needs it — the category chip row if it needs
scroll affordances (otherwise plain CSS overflow-x, no client needed). Prefer no client.
## Files likely to change / add
- `app/page.tsx` — replace placeholder with the full home layout (top bar, header, chip row,
Top News heading, card grid). Composes the sections below.
- `components/layout/top-bar.tsx` — dark utility bar: Browser Extension · Theme toggle (left);
date · Set Location · Edition dropdown (right).
- `components/layout/site-header.tsx` — hamburger, "Skew News" wordmark, nav (Home active /
For You (dot) / Local / Blindspot), Subscribe (primary) + Login (secondary/outline).
- `components/layout/category-bar.tsx` — horizontally scrollable row of `Chip` (addable),
leading `+`, `overflow-x-auto` with hidden scrollbar; no page horizontal overflow.
- `components/layout/site-footer.tsx` — dark footer: Skew News mark + tagline, Company / Help
columns, Connect social icons, copyright. (Reference shows it; include for completeness.)
- `components/ui/news-card.tsx` — vertical card: 16:9 image with info icon top-right,
`category · country` caption, title (`text-h3`/tighter), compact bias meter, `N sources` footer.
- `components/ui/bias-meter.tsx` — add additive compact/short-left option (see decisions).
- `lib/mock/news.ts` — typed `MOCK_ARTICLES` (12 items mirroring the reference).
- Possibly `lib/types.ts` — a shared `NewsArticleCard` type used by mock + card props.
## Visual interpretation (from reference)
- **Top bar:** full-width, near-black bg, `text-caption` light-gray text, ~40px tall. Left:
"Browser Extension", then "Theme:" with Light (active/bold) · Dark · Auto. Right: full date,
"Set Location", globe + "International Edition" + chevron. Divider dots between right items.
- **Header:** white, ~72px, bottom border. Left cluster: hamburger icon, then "Skew" (bold,
~`text-h2`) + "News" (secondary, smaller, baseline-aligned). Center nav: Home (active —
bold + underline), For You (with small accent dot super), Local, Blindspot — `text-body-md`.
Right: Subscribe (primary dark) + Login (outline/secondary), rounded-md.
- **Category bar:** thin white strip under header, bottom border. Chips are pill outline with a
trailing `+`, `text-body-sm`, ~8px gap, horizontally scrollable, faint `+` at far left and a
chevron affordance at the right edge.
- **Top News:** `text-h2`/`text-h1`-ish bold heading, generous top margin, left-aligned to the
1280px container.
- **Card grid:** 3 columns desktop (24px gutter), 2 columns tablet, 1 column mobile. Each card:
white, `rounded-lg`, `border`, subtle shadow, `p`-4. Image 16:9 `rounded-md`, circular info
icon top-right over image. Below: `Category · Country` caption (secondary), 2-line title,
full-width bias meter (L/Center/Right), then `N sources` in secondary caption.
- **Footer:** near-black, multi-column, light text, social icons row.
- **Colors/spacing/type:** use existing `@theme` tokens and `.text-*` utilities only — no new
hardcoded hex. Container `max-w-[--container-app]` centered with 24px side padding.
## Implementation requirements
- TypeScript, explicit prop types, no `any`. Small focused components; no mixed UI/business logic.
- Preserve server/client boundaries (§21): presentational components, Server Components by default.
- Use design tokens + type utilities, not ad-hoc hex/px where a token exists.
- Reuse existing primitives (`Button`, `Chip`, `BiasMeter`) — extend, don't fork.
- Inline SVGs for icons (match existing `article-card` icon style); no new icon dependency.
- No scraping/analysis/network/secret code anywhere in these components (§21).
## Security requirements
- Pure UI; no secrets, no server-only keys, no network calls, no pipeline state. Nothing to expose.
## Acceptance criteria
- `/` renders top bar, header, category bar, "Top News", a 12-card responsive grid, and footer,
visually matching the reference.
- Cards show image + info icon, `category · country`, title, L/Center/Right bias meter with
percentages summing to 100, and `N sources`.
- Grid is 3-col ≥1024px, 2-col ≥640px, 1-col below; no horizontal page overflow at 375px.
- Category row scrolls horizontally without pushing page width.
- `article-card.tsx` and the design-system page remain unchanged and still build.
- Light-only, deterministic; Poppins throughout.
## Checks to run
- `npm run typecheck`
- `npm run lint`
- `npm run build` (new routes/components)
## Manual test steps
1. `npm run dev`.
2. Open `http://localhost:3000/` — verify top bar, header/nav, category chips, Top News heading,
the 12-card grid, and footer against the reference image.
3. Resize to ~1024px (2–3 col), ~768px (2 col), ~375px (1 col) — confirm no horizontal overflow
and the category row scrolls rather than widening the page.
4. Confirm bias meters render proportional L/Center/Right segments with correct percentages and
`N sources` under each card.
5. Confirm `/design-system` still renders unchanged.
这份 prompts/home-page-ui.md 文件是 AI 助手生成的第二份详细实施计划书。
在完成了上一个“设计系统”的任务后，这份计划书旨在利用已经建好的基础 UI 组件，拼装出 SKEW 网站的首页。
下面为你逐个模块进行技术拆解：
1. Goal (目标)
解释：
- 核心任务：搭建首页（
app/page.tsx），包含：顶部工具栏、吸顶的网站 Header（含导航和登录按钮）、可横向滑动的分类标签行、“Top News”标题区、以及响应式的 3 列新闻卡片网格。 - 关键约束：依然是纯 UI 展示。因为数据库还没建好，所以禁止接入真实数据或爬虫逻辑。AI 必须造一批强类型的假数据来渲染页面。这样以后接真数据库时，只需换数据源，UI 组件一行都不用改。
2. Decisions / assumptions (关键决策与技术选型)
解释：
这是 AI 在面对具体问题时做出的架构决策，非常关键：
- 新建垂直卡片组件：设计系统里之前建的是“横向”的文章卡片，但首页要求的是“图片在上、内容在下”的垂直卡片。AI 决定不修改老组件，而是新建一个
news-card.tsx，保证向后兼容。 - 使用 Mock 假数据：新建
lib/mock/news.ts放假数据。数据结构必须和未来真实数据库的字段一模一样。 - 优雅扩展偏见指标条：设计稿里首页的卡片空间有限，偏见指标条左边的标签显示为简写的
L 20%（而不是Left 20%）。AI 决定给BiasMeter组件增量添加一个variant="compact"属性，而不是去重写原有的逻辑，确保不破坏设计系统展示页。 - 纯展示性交互：顶部栏的“主题切换”、“登录”、“订阅”按钮目前只是画个样子，不接入任何真实逻辑（因为 Clerk 认证还没做，且目前只有浅色主题）。
- 坚持服务端组件：首页和卡片默认全是 Server Component，除非横向滑动列表真的需要前端交互，否则绝不加
"use client"。
3. Files likely to change / add (即将修改/新增的文件清单)
解释：
AI 列出了具体的施工清单：
app/page.tsx：重写首页，组合各个区域。components/layout/：新建四个布局组件（顶部栏top-bar、页头site-header、分类滑动条category-bar、页脚site-footer）。components/ui/news-card.tsx：新建垂直新闻卡片。components/ui/bias-meter.tsx：微调，增加紧凑模式。lib/mock/news.ts&lib/types.ts：新建假数据和 TypeScript 类型定义。
4. Visual interpretation (视觉还原要求)
解释：
这是给 AI 定下的“像素级”还原指南，描述得非常细致：
- 顶部栏：近黑色背景，约 40px 高，左边是浏览器扩展和主题切换，右边是日期和地区选择。
- Header：白色，约 72px 高。左边是汉堡菜单和“Skew News” Logo。中间导航栏的“Home”要有激活态（加粗下划线），“For You”上面要有个小圆点。右边是订阅和登录按钮。
- 分类滑动条：必须是
overflow-x-auto（横向滚动），且不能导致整个页面出现横向滚动条。 - 卡片网格：桌面端 3 列（24px 间距），平板 2 列，手机 1 列。卡片图片要是 16:9，右上角要有信息图标。
5. Implementation requirements (实现要求)
解释：
- 类型严格：TypeScript 明确定义 Props，禁止用
any。 - 边界控制：遵守服务端/客户端边界。
- 只用令牌：必须用上一阶段建好的
@theme令牌（如text-secondary,rounded-lg），严禁在代码里硬编码颜色十六进制值。 - 复用组件：必须复用已有的
Button、Chip等基础组件，不要造轮子。图标用内联 SVG，不引新的图标库。
6. Security & Acceptance criteria (安全与验收标准)
解释：
- 安全：纯前端 UI，无网络请求，无密钥，绝对安全。
- 验收标准：
- 访问
/能看到完整的首页结构。 - 卡片必须包含：图片、分类·国家、标题、总和为 100% 的偏见指标条、来源数量（N sources）。
- 响应式红线：在 1024px 变 2-3 列，768px 变 2 列，375px 变 1 列，且 375px 时整个页面绝对不能出现横向滚动条（分类栏必须自己内部滚动）。
- 之前建好的
/design-system页面必须保持原样不受影响。
- 访问
7. Checks & Manual test steps (检查与测试步骤)
解释：
- 跑
typecheck,lint,build。 - 手动测试：启动项目，对比设计稿检查首页。把窗口缩到手机大小（375px）检查横向滚动条。检查偏见指标条的比例和百分比是否正确。
总结
这份计划书完美体现了**“关注点分离”**的架构思想。AI 被严格要求：只管画皮（UI），不管填瓤（数据）。通过引入强类型的 Mock 数据，AI 可以把首页的响应式布局、组件复用、视觉细节打磨到极致，而不用等待后端的 Supabase 或 Oxylabs 爬虫开发完毕。等你点头同意（approve）后，AI 才会按照这份说明书开始敲代码。
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
8
0- 0
已为社区贡献3条内容
所有评论(0)