newsui/design.md

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"] 后是暖深棕黑（不是冷黑）