sunzhongyi
1f09bba3ef
- 18 React components (Layout/Section/Article/Layer/Masthead/Rule + Headline/Subhead/Kicker/BodyText/Quote/Byline/Dateline/Caption + Image/Figure/Video/PullQuote) - Theme: warm off-white palette, Source Serif 4 / Cormorant Garamond / Inter / Noto Serif SC/JP, visual weight mapping, dark mode - Docs: Landing page, 6 Blocks (zh/en/jp), component API docs - GitHub Pages deployment via static export Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
224 lines
12 KiB
Markdown
224 lines
12 KiB
Markdown
|
||
# AI Agent Prompt: 生产级报纸组件库开发
|
||
|
||
## 任务目标
|
||
开发一个浏览器端生产级报纸布局组件库，参考 InDesign 与经典严肃风（NYT / The Times）排版传统，组件少而精、职责明确、无冗余、无歧义，支持全局 24 列栅格、跨栏、视觉权重和主题系统，提供文档网站（内嵌 demo，无需 storybook）。
|
||
|
||
视觉基调：经典严肃风（衬线为主、暖灰系、warm off-white 背景、双线分隔、首字下沉、栏间细线、真实多栏文字流）。
|
||
|
||
---
|
||
|
||
## 1. 项目 setup 与架构
|
||
|
||
- **Monorepo 管理**（pnpm workspace + Turborepo）
|
||
- Packages:
|
||
1. `components` → Layout / Section / Article / Layer / Masthead / Rule / Headline / Subhead / Kicker / BodyText / Quote / Byline / Dateline / Caption / Image / Figure / Video / PullQuote
|
||
2. `theme` → 字体导入、CSS variables、视觉权重映射、Tailwind tokens、排版工具类
|
||
3. `docs` → 文档网站（Next.js + Tailwind + MDX）
|
||
4. `utils` → 栅格校验（`validateSpan` / `clampSpan`）、`cx` 类名合并
|
||
|
||
- **目录结构**:
|
||
```
|
||
/packages
|
||
/components
|
||
/src
|
||
/layout (Layout / Section / Article / Layer / Masthead / Rule)
|
||
/text (Headline / Subhead / Kicker / BodyText / Quote / Byline / Dateline / Caption)
|
||
/media (Image / Figure / Video / PullQuote)
|
||
/theme
|
||
/src
|
||
fonts.css (Google Fonts: Cormorant Garamond / Source Serif 4 / Inter / UnifrakturMaguntia)
|
||
variables.css (CSS variables: 字体 / 暖灰系颜色 / 间距 / 分隔线 / 强调色)
|
||
typography.css (drop-cap / small-caps / paragraph-flow / OSF / column-rule 等工具类)
|
||
visual-weights.ts
|
||
tailwind.config.js
|
||
/docs
|
||
/utils
|
||
```
|
||
|
||
- **技术栈**:
|
||
- React 18+, TypeScript 5+
|
||
- TailwindCSS 3+ + 文档站基础 stack
|
||
- Vitest + React Testing Library
|
||
- 构建：Vite + Rollup（components/theme/utils）；Next.js 14+（docs）
|
||
|
||
---
|
||
|
||
## 2. 全局栅格系统
|
||
|
||
- `<Layout>` 顶层容器：
|
||
- `columns`（默认 24）、`maxWidth`、`padding`、`theme`（'light' | 'dark'）
|
||
- 通过 React Context 把 columns 下传给 `<Section>`
|
||
- `<Section>` 内部使用 `display: grid; grid-template-columns: repeat(N, 1fr); gap: var(--nui-gutter)`
|
||
- Section 内对象通过 `grid-column: span N` 跨栏，统一布局机制
|
||
- 响应式：通过 CSS media query / container query 调整（不再使用 JS 路径）
|
||
|
||
---
|
||
|
||
## 3. 核心布局组件
|
||
|
||
1. `<Section>`：
|
||
- `columns`（必填）、`gap`、`breakable`、`divider`（'none' | 'top' | 'bottom' | 'both'）
|
||
- 内部对象 span ≤ Section.columns，超过自动 clamp 并 console.warn
|
||
|
||
2. `<Article>`：
|
||
- `span`、`breakable`
|
||
- 跨栏统一通过 `grid-column: span N`
|
||
|
||
3. `<Layer>`：
|
||
- `position`（'absolute' | 'fixed' | 'sticky'）、`top/left/right/bottom`、`zIndex`
|
||
|
||
4. `<Masthead>` 报头组件：
|
||
- `title`、`kicker`、`edition`、`date`、`price`
|
||
- `variant`：'classic'（双线居中 + Cormorant Garamond）、'blackletter'（UnifrakturMaguntia 哥特体）、'modern'（左对齐 + accent 色）
|
||
|
||
5. `<Rule>` 分隔线组件：
|
||
- `variant`：'hairline' | 'double' | 'thick'
|
||
- `orientation`：'horizontal' | 'vertical'
|
||
- `span`（横向时占多少列，默认 `1 / -1`）
|
||
|
||
---
|
||
|
||
## 4. 内容组件
|
||
|
||
- 文本类：`<Headline>` / `<Subhead>` / `<Kicker>` / `<BodyText>` / `<Quote>` / `<Byline>` / `<Dateline>` / `<Caption>`
|
||
- 媒体类：`<Image>` / `<Figure>` / `<Video>` / `<PullQuote>`
|
||
- 通用属性：`weight`、`span`（跨栏，由 Section 的 grid-column 提供）、`className`、`style`
|
||
- `<BodyText>` 核心扩展：
|
||
- `columns?: 1 | 2 | 3 | 4` 启用 CSS multi-column 真实多栏文字流
|
||
- `dropCap?: boolean` 首字下沉
|
||
- 默认开启段间无空行 + 第二段起首行缩进 1em + old-style figures + hanging punctuation
|
||
- `<Quote>`：`variant: 'block' | 'inline'`，block 用左缩进 1.5em（不使用左 border）
|
||
- `<PullQuote>`：上下双 hairline + Display 字体；`spanAllColumns` 在多栏 BodyText 内自动跨所有栏
|
||
- `<Byline>` / `<Dateline>` / `<Kicker>`：使用真小帽（OpenType `font-variant-caps: small-caps`，非 `text-transform: uppercase`）
|
||
|
||
---
|
||
|
||
## 5. 视觉权重映射表（修订版）
|
||
|
||
经典严肃风修订要点：
|
||
- 字号上限放开（Headline High 48–72px，原 36–48px 太小压不住头版）
|
||
- font-weight 普遍下调（High 700 → 600，Medium 600 → 500），避免数码黑
|
||
- line-height 衬线上调（BodyText 1.55–1.6）
|
||
- 颜色使用暖灰系 token（`--nui-text-primary` `#1A1A1A` 而非 `#111`）
|
||
- 颜色 / 字体均通过 CSS variable token，不硬编码 hex
|
||
- 新增 4 档：Masthead / Kicker / Dateline / Caption credit
|
||
|
||
| 组件 | 权重 | font-family | font-size | font-weight | line-height | letter-spacing | font-variant | color | span | margin |
|
||
|---|---|---|---|---|---|---|---|---|---|---|
|
||
| Masthead | Standard | `--font-family-masthead` | 56–96px | 700 | 1.0 | 0.02em | lining-nums | `--nui-text-primary` | 24 | 0 |
|
||
| Headline | High | `--font-family-display` | 48–72px | 600 | 1.05 | -0.01em | lining-nums + balance | `--nui-text-primary` | 8–16 | `0 0 1rem 0` |
|
||
| Headline | Medium | `--font-family-headline` | 32–40px | 600 | 1.1 | -0.005em | lining-nums | `--nui-text-primary` | 6–10 | `0 0 0.75rem 0` |
|
||
| Headline | Low | `--font-family-headline` | 22–26px | 500 | 1.2 | 0 | lining-nums | `--nui-text-body` | 4–6 | `0 0 0.5rem 0` |
|
||
| Subhead | High | `--font-family-headline` italic | 18–22px | 500 | 1.3 | 0 | oldstyle-nums | `--nui-text-secondary` | 4–8 | `0 0 0.75rem 0` |
|
||
| Subhead | Medium | `--font-family-headline` italic | 16–18px | 400 | 1.35 | 0 | oldstyle-nums | `--nui-text-secondary` | 2–4 | `0 0 0.5rem 0` |
|
||
| Kicker | Standard | `--font-family-meta` small-caps | 12–13px | 600 | 1.2 | 0.08em | small-caps + lining | `--nui-accent-primary` | 1–4 | `0 0 0.25rem 0` |
|
||
| BodyText | High | `--font-family-body` | 16–17px | 400 | 1.6 | 0 | oldstyle-nums | `--nui-text-body` | 1 | `0 0 0.75rem 0` |
|
||
| BodyText | Medium | `--font-family-body` | 15px | 400 | 1.55 | 0 | oldstyle-nums | `--nui-text-body` | 1 | `0 0 0.5rem 0` |
|
||
| BodyText | Low | `--font-family-body` | 13–14px | 400 | 1.5 | 0 | oldstyle-nums | `--nui-text-secondary` | 1 | `0 0 0.5rem 0` |
|
||
| Quote (block) | High | `--font-family-body` | 17–19px | 400 | 1.55 | 0 | oldstyle-nums | `--nui-text-quote` | 2 | `1rem 0 1rem 1.5em` |
|
||
| Quote (inline) | — | `--font-family-body` italic | inherit | 400 | inherit | 0 | inherit | inherit | — | 0 |
|
||
| PullQuote | High | `--font-family-display` | 26–32px | 600 | 1.2 | -0.005em | lining-nums + balance | `--nui-text-primary` | 2–3 | `1.5rem 0` |
|
||
| PullQuote | Medium | `--font-family-display` | 20–24px | 500 | 1.25 | 0 | lining-nums | `--nui-text-body` | 1–2 | `1rem 0` |
|
||
| Caption | Standard | `--font-family-body` italic | 13px | 400 | 1.4 | 0 | oldstyle-nums | `--nui-text-secondary` | 1 | `0.5rem 0 0 0` |
|
||
| Caption credit | — | `--font-family-meta` small-caps | 11–12px | 500 | 1.4 | 0.06em | small-caps | `--nui-text-muted` | 1 | inline |
|
||
| Byline | Standard | `--font-family-meta` small-caps | 12–13px | 500 | 1.3 | 0.06em | small-caps + lining | `--nui-text-secondary` | 1 | `0 0 0.25rem 0` |
|
||
| Dateline | Standard | `--font-family-meta` small-caps | 12–13px | 600 | 1.3 | 0.08em | small-caps + lining | `--nui-text-primary` | 1 | inline |
|
||
|
||
---
|
||
|
||
## 6. 主题系统
|
||
|
||
### 6.1 字体（Google Fonts，免费可商用）
|
||
- `--font-family-masthead`：Cormorant Garamond（报头主字）
|
||
- `--font-family-blackletter`：UnifrakturMaguntia（哥特报头 preset）
|
||
- `--font-family-display` / `--font-family-headline` / `--font-family-body`：Source Serif 4（Optical Size 可变字体，覆盖头条到正文）
|
||
- `--font-family-meta`：Inter（Byline / Dateline / Kicker / Caption credit 用真小帽）
|
||
|
||
### 6.2 颜色（暖灰系，避开纯黑/纯白）
|
||
|
||
Light（默认）：
|
||
- 页面背景：`--nui-bg-page #F7F4ED`、`--nui-bg-surface #FBF9F4`
|
||
- 文字：`--nui-text-primary #1A1A1A`、`--nui-text-body #22201C`、`--nui-text-secondary #4A4742`、`--nui-text-muted #6E6A63`、`--nui-text-quote #2E2A24`
|
||
- 分隔线：`--nui-rule-hairline #C9C2B2`、`--nui-rule-decorative #1A1A1A`
|
||
- 强调色：`--nui-accent-primary #7A1F1F`（NYT 朱红）、`--nui-accent-ink-blue #1B2A4A`（The Times 蓝）、`--nui-highlight #F2E9C8`（旧报纸黄）
|
||
|
||
Dark（暖深棕黑，非冷黑）：
|
||
- 反向映射保持暖意，accent 色提亮 + 降饱和
|
||
|
||
### 6.3 间距 / 排版工具类
|
||
- 间距 token：`--nui-gutter`、`--nui-space-{1,2,3,4,6,8}`
|
||
- 排版工具类（typography.css）：
|
||
- `.nui-drop-cap` 首字下沉（`::first-letter` + `float: left`）
|
||
- `.nui-small-caps` 真小帽（OpenType `smcp/c2sc`）
|
||
- `.nui-paragraph-flow` 段间无空行 + `p + p` 首行缩进 1em
|
||
- `.nui-osf` old-style figures、`.nui-tnum` tabular figures
|
||
- `.nui-hanging-punctuation` 悬挂引号
|
||
- `.nui-column-rule` 栏间 hairline
|
||
- `.nui-avoid-break` `break-inside: avoid`
|
||
- `.nui-span-all-columns` `column-span: all`（多栏内跨栏）
|
||
- `.nui-masthead-rule-top` / `.nui-masthead-rule-bottom` 报头双线
|
||
|
||
### 6.4 主题切换
|
||
通过 `[data-theme="dark"]` 覆盖 CSS variables，组件代码无需感知主题；提供手动切换按钮。
|
||
|
||
---
|
||
|
||
## 7. 布局规则
|
||
|
||
- Section 内对象 span ≤ Section.columns，超过自动 clamp + console.warn（不抛异常崩溃）
|
||
- 高权重对象可跨多栏（Headline High 跨 8–16 列）
|
||
- Layer 浮动/绝对定位，脱离栅格流
|
||
- `breakable` 控制打印分页断开（`break-inside: auto | avoid`）
|
||
- BodyText 多栏：`columns: 1 | 2 | 3 | 4` 启用 CSS multi-column；通过 `column-rule: 1px solid var(--nui-rule-hairline)` 渲染栏间细线；标题与 PullQuote 自动 `break-inside: avoid` 避免被切断
|
||
- 响应式：通过 CSS media query / container query 在小屏调整列数与栏宽（不使用 JS 路径）
|
||
|
||
---
|
||
|
||
## 8. 文档网站
|
||
|
||
- 技术栈：Next.js + Tailwind + MDX
|
||
- 页面：所有 demo 用真实组件渲染，非 mockup
|
||
- 路由结构：
|
||
1. `/` 首页 = 报纸风格 Landing Page（Masthead + 介绍 + 多语言 demo 列表 + 设计哲学/技术栈）
|
||
2. `/examples/nyt-frontpage` NYT 派完整报纸头版（Masthead + Briefs + Lead Story 含 hero image + 3 栏 BodyText + drop cap + PullQuote + Secondary + Third Story 4 栏）
|
||
3. `/grid-system` 栅格系统与 Layout/Section/Article/Layer 说明
|
||
4. `/components/masthead` Masthead 三种 variant 对照
|
||
5. `/components/article` Article + Layer 跨栏与浮动 demo
|
||
6. `/components/rule` Rule 三种 variant 对照
|
||
7. `/components/media` Image / Figure / Video / PullQuote
|
||
8. `/text` 文本组件全集 + 视觉权重映射表（实时渲染）+ 多栏文字流 demo + drop cap demo
|
||
9. `/theme` CSS variables 列表 + color swatch + 暗色主题切换按钮
|
||
10. `/examples/spanning` 跨栏布局示例
|
||
11. `/examples/responsive` 响应式布局展示
|
||
12. `/examples/blackletter-frontpage` The Times / FAZ 派哥特体头版 preset
|
||
- 全局导航：顶部 Header（Docs / Components / Themes / Blocks / GitHub），文档区域内嵌 Sidebar 二级导航
|
||
|
||
---
|
||
|
||
## 9. 实施顺序
|
||
|
||
1. 初始化 monorepo（pnpm workspace + Turborepo）
|
||
2. 实现 theme（字体导入 + 暖灰系 CSS variables + 视觉权重表 + 排版工具类 + Tailwind tokens）
|
||
3. 实现 utils（`validateSpan` / `clampSpan` / `cx`）
|
||
4. 实现 components 三层（layout / text / media）；统一 grid-column span 跨栏机制；BodyText 接入 CSS multi-column
|
||
5. 测试生产级头版：跨栏、多栏文字流、首字下沉、栏间 hairline、真小帽、Pull Quote 跨栏、breakable、响应式
|
||
6. 构建文档网站，首页为报纸风格 Landing Page 汇聚多语言 demo，`/examples/nyt-frontpage` 作为 NYT 派生产级标杆，章节页用真实组件 demo
|
||
7. 验收：视觉与传统报纸排版（NYT / The Times / FAZ）一致；自动化构建/测试通过；Design Agent 复评 ≥ 9/10
|
||
|
||
---
|
||
|
||
## 10. 验收标准
|
||
|
||
打开 `/examples/nyt-frontpage` 应满足：
|
||
- Masthead 是 Cormorant Garamond 衬线 + 双线分隔
|
||
- 头条字号 ≥ 48px、line-height ≤ 1.15、字重 600
|
||
- 头条下方 BodyText 真分 3 栏，栏间有 1px 暖灰 hairline
|
||
- 第一段开头有真实 drop cap（占 2–3 行）
|
||
- Byline / Dateline / Kicker 是 Inter 真小帽（不是 uppercase 伪小帽）
|
||
- PullQuote 上下双 hairline、字号 26–32px
|
||
- 配色是 warm off-white + 暖深灰，不是 `#FFFFFF` + `#000000`
|
||
- 数字是 old-style figures（3 / 5 / 7 有下伸笔）
|
||
- 段间无空行，第二段起首行缩进 1em
|
||
- 切换 `[data-theme="dark"]` 后是暖深棕黑（不是冷黑）
|