lucida

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lucida

YAML-native slide deck builder. Content lives in

.slides.yaml

files, themes control all visual styling, and the CLI produces self-contained HTML or 16:9 PDF.

原生支持YAML的幻灯片构建工具。内容存储在

.slides.yaml

文件中，主题控制所有视觉样式，CLI可生成独立的HTML或16:9比例的PDF。

Quick Start

快速开始

bash

npx lucida-slides build deck.slides.yaml           # → deck-slides.html
npx lucida-slides pdf deck.slides.yaml             # → deck-slides.html + deck-slides.pdf
npx lucida-slides pdf deck.slides.yaml --open      # build + open PDF
npx lucida-slides build content/*.slides.yaml      # batch build

Output lands in the current working directory. HTML files are fully self-contained (all CSS, JS, and font imports inlined). PDF requires Playwright — install once with

npx playwright install chromium

bash

npx lucida-slides build deck.slides.yaml           # → deck-slides.html
npx lucida-slides pdf deck.slides.yaml             # → deck-slides.html + deck-slides.pdf
npx lucida-slides pdf deck.slides.yaml --open      # 构建并打开PDF
npx lucida-slides build content/*.slides.yaml      # 批量构建

输出文件会保存在当前工作目录。HTML文件是完全独立的（所有CSS、JS和字体导入都已内联）。导出PDF需要Playwright，可执行

npx playwright install chromium

一次性完成安装。

Design Philosophy

设计理念

Lucida deliberately breaks the "one idea per slide" convention. Traditional presentation advice says to minimize text and use big images. Lucida takes the opposite approach: information-dense slides that respect the audience's intelligence.

This works because Lucida decks are built for contexts where the audience wants depth — board meetings, analyst presentations, strategy reviews, data-driven recommendations. The audience is reading, not passively watching. A single Lucida slide often carries a data table, 2-3 interpretive callouts, and stat boxes — the equivalent of 3-4 traditional slides, but better because the data and its interpretation live side by side.

The key principles:

Titles are insights, not labels. "ARR grew 50% QoQ — driven by enterprise" not "Revenue Overview"
Never present data without interpretation. Every table gets callouts explaining what matters.
Colors encode meaning. Green = positive, red = problem, amber = caution, navy = strategic context, gold = opportunity.
Narrative arc matters. Hero → data → deep dives → risks → priorities → close.
Variants create rhythm. Most slides are default; hero opens, dark closes, alert signals risk, warm provides visual variety.

For the full guide on writing compelling decks, read

references/slide-craft.md

Lucida刻意打破了「每页幻灯片只讲一个观点」的常规。传统演示建议认为应该尽量减少文字、多用大图，而Lucida走的是相反的路线：信息密度高的幻灯片，尊重受众的智商。

这种设计适用于受众需要深度信息的场景：董事会会议、分析师汇报、战略复盘、数据驱动的建议方案。受众是在阅读内容，而不是被动观看。单张Lucida幻灯片通常可以承载一个数据表、2-3个解释标注和统计框，相当于3-4张传统幻灯片的信息量，而且优势在于数据和解释可以并排展示。

核心原则：

标题是洞察结论，不是分类标签。 要用「ARR环比增长50%——由企业业务驱动」而不是「收入概览」
永远不要只展示数据不加解释。 每个表格都要有标注说明重点是什么。
颜色承载含义。 绿色=正面，红色=问题，琥珀色=提醒，深蓝色=战略背景，金色=机会。
叙事逻辑很重要。 开场→数据→深度分析→风险→优先级→收尾。
变体样式创造节奏。 大部分幻灯片用默认样式，开场用hero样式，收尾用dark样式，风险提示用alert样式，暖色调样式提供视觉变化。

要了解编写有吸引力的幻灯片的完整指南，可阅读

references/slide-craft.md

。

Reading Strategy

阅读指南

Read this file first. Only read reference docs when needed:

Writing deck content? → Read
```
references/slide-craft.md
```
first for narrative and design guidance
Need component syntax? → This file covers all components
Creating a custom theme? →
```
references/themes.md
```
Need a starter template? →
```
examples/starter-deck.md
```

先读本文档，仅在需要时查阅参考文档：

要编写幻灯片内容？→ 先读
```
references/slide-craft.md
```
获取叙事和设计指导
需要组件语法？→ 本文档涵盖所有组件用法
要创建自定义主题？→ 查阅
```
references/themes.md
```
需要初始模板？→ 参考
```
examples/starter-deck.md
```

Content Format

内容格式

Every deck is a single YAML file with two top-level keys:

yaml

meta:
  title: "Deck Title"
  theme: aurora              # theme name (resolves to themes/<name>.yaml)
  footer: "Company · Q4 2025"
  lang: en

slides:
  - variant: hero
    title: "Welcome"
    # ... slide content

每个幻灯片集都是单个YAML文件，包含两个顶级键：

yaml

meta:
  title: "幻灯片集标题"
  theme: aurora              # 主题名称（对应themes/<name>.yaml）
  footer: "公司名称 · 2025年第四季度"
  lang: en

slides:
  - variant: hero
    title: "欢迎"
    # ... 幻灯片内容

Meta Fields

Meta字段

Field	Required	Description
`title`	yes	HTML `<title>` and deck identifier
`theme`	yes	Theme file name (without `.yaml` )
`footer`	no	Text shown in bottom nav bar
`lang`	no	HTML lang attribute (default: `da` )
`custom_css`	no	Raw CSS injected after all theme/component styles

字段	必填	说明
`title`	是	HTML `<title>` 内容和幻灯片集标识
`theme`	是	主题文件名（不含 `.yaml` 后缀）
`footer`	否	底部导航栏显示的文字
`lang`	否	HTML lang属性（默认值： `da` ）
`custom_css`	否	在所有主题/组件样式之后注入的原生CSS

Slide Structure

幻灯片结构

Each slide is a YAML object in the

slides

array:

yaml

- variant: hero              # optional: hero, dark, warm, alert
  label: "Section Name"      # small uppercase label above title
  title: "Slide Title"       # main heading
  title_style: "font-size:52px;"  # optional inline CSS
  subtitle: "Explanatory text"
  subtitle_style: "..."
  # ... then components (kpis, table, bullets, etc.)
  # ... or layout with columns

每张幻灯片都是

slides

数组中的一个YAML对象：

yaml

- variant: hero              # 可选：hero, dark, warm, alert
  label: "板块名称"          # 标题上方的小写字样标签
  title: "幻灯片标题"       # 主标题
  title_style: "font-size:52px;"  # 可选的行内CSS
  subtitle: "说明文字"
  subtitle_style: "..."
  # ... 接下来是组件（kpis、table、bullets等）
  # ... 或者用分栏布局

Variants

变体样式

Variants change the slide's background and text color. Defined in the theme:

Variant	Typical use
(none)	Default light background
`hero`	Title/opening slides — bold gradient, white text
`dark`	Closing/summary slides — dark gradient, white text
`warm`	Soft tinted background for variety
`alert`	Light red/pink for risk or warning slides

变体样式会改变幻灯片的背景和文字颜色，在主题中定义：

变体	典型使用场景
（无）	默认浅色背景
`hero`	标题/开场页——粗体渐变背景，白色文字
`dark`	收尾/总结页——深色渐变背景，白色文字
`warm`	柔和浅色调背景，用于增加视觉变化
`alert`	浅红/粉色背景，用于风险或警告类幻灯片

Text Formatting

文本格式

Inline formatting works in any text field (titles, subtitles, bullet text, table cells):

Syntax	Result
`bold text`	bold text
`text{.green}`	Colored text using theme CSS variable
`--`	en-dash (–)
`---`	em-dash (—)
`&entity;`	HTML entities passed through ( `·` , `→` , etc.)

任何文本字段（标题、副标题、列表文字、表格单元格）都支持行内格式：

语法	效果
`粗体文字`	粗体文字
`text{.green}`	调用主题CSS变量的彩色文字
`--`	半角破折号（–）
`---`	全角破折号（—）
`&entity;`	直接传递HTML实体（ `·` 、 `→` 等）

Components

组件

Components are the building blocks of slide content. They can appear at the slide level, inside columns, inside cards, or nested in content arrays.

组件是幻灯片内容的构建块，可放在幻灯片层级、分栏内、卡片内，或嵌套在内容数组中。

KPIs

KPI指标

Large numbers with labels — ideal for hero slides.

yaml

kpis:
  - value: "$10.2M"
    label: "ARR"
  - value: "130%"
    label: "net dollar retention"
  - value: "94%"
    label: "gross margin"

带标签的大号数字，非常适合开场页使用。

yaml

kpis:
  - value: "$10.2M"
    label: "ARR"
  - value: "130%"
    label: "净收入留存率"
  - value: "94%"
    label: "毛利率"

Table

表格

Data tables with optional row highlighting and cell formatting.

yaml

table:
  headers: ["Segment", "ARR", "Growth"]
  rows:
    - ["Enterprise", "$5.8M", "+68%"]                        # simple row
    - row: ["Mid-Market", "$2.9M", "+41%"]                   # row with options
      highlight: green                                        # tints row background
      style: "border-top:2px solid var(--border);"           # custom CSS
    - ["SMB", {text: "$1.5M", color: red, bold: true}, "+12%"]  # formatted cell

Cell formatting — use a dict instead of a string:

```
text
```
or
```
value
```
: display text
```
color
```
: theme color name (e.g.,
```
green
```
,
```
red
```
,
```
primary
```
)
```
bold
```
: true for font-weight:600
```
style
```
: raw CSS string

支持可选行高亮和单元格格式的数据表格。

yaml

table:
  headers: ["业务板块", "ARR", "增长率"]
  rows:
    - ["企业业务", "$5.8M", "+68%"]                        # 普通行
    - row: ["中端市场", "$2.9M", "+41%"]                   # 带配置的行
      highlight: green                                        # 给行背景加底色
      style: "border-top:2px solid var(--border);"           # 自定义CSS
    - ["SMB", {text: "$1.5M", color: red, bold: true}, "+12%"]  # 带格式的单元格

单元格格式——用字典代替字符串：

```
text
```
或
```
value
```
：展示的文字
```
color
```
：主题颜色名称（例如
```
green
```
、
```
red
```
、
```
primary
```
）
```
bold
```
：设为true则字重为600
```
style
```
：原生CSS字符串

Bullets

列表项

Bullet list with optional sub-text.

yaml

bullets:
  - text: "Main point"
    sub: "Supporting detail"
  - text: "Another point"

带可选附属文字的项目符号列表。

yaml

bullets:
  - text: "核心观点"
    sub: "支撑细节"
  - text: "另一个观点"

Callout

标注框

Colored info/alert box with title and body text.

yaml

callout:
  color: green          # primary, green, gold, red, amber, navy
  title: "Key insight"
  text: "Explanation here."
  style: "margin-top:16px;"   # optional

带标题和正文的彩色信息/提示框。

yaml

callout:
  color: green          # primary, green, gold, red, amber, navy
  title: "关键洞察"
  text: "解释内容放在这里。"
  style: "margin-top:16px;"   # 可选

Stat Boxes

统计框

Row of bordered boxes with big numbers.

yaml

stat_boxes:
  - value: "$10.2M"
    label: "total ARR"
    color: green        # optional: colors the value
  - value: "528"
    label: "customers"

一排带边框的盒子，展示大号数字。

yaml

stat_boxes:
  - value: "$10.2M"
    label: "总ARR"
    color: green        # 可选：给数值上色
  - value: "528"
    label: "客户数"

Bar Chart

条形图

Horizontal bars for simple comparisons.

yaml

bar_chart:
  bars:
    - label: "Q1"
      width: "32%"
      value: "$3.2M"
      color: "var(--primary-light)"
    - label: "Q4"
      width: "100%"
      value: "$10.2M"
      color: "var(--primary)"

Bars support

ghost

overlays for before/after comparisons:

yaml

    - label: "Product A"
      width: "65%"
      value: "65%"
      color: green
      ghost:
        width: "80%"
        color: amber

用于简单对比的水平条形图。

yaml

bar_chart:
  bars:
    - label: "第一季度"
      width: "32%"
      value: "$3.2M"
      color: "var(--primary-light)"
    - label: "第四季度"
      width: "100%"
      value: "$10.2M"
      color: "var(--primary)"

条形图支持

ghost

覆盖层，可用于前后对比：

yaml

    - label: "产品A"
      width: "65%"
      value: "65%"
      color: green
      ghost:
        width: "80%"
        color: amber

Donut Chart

环形图

Circular composition chart — shows how parts make up a whole.

yaml

donut_chart:
  size: 120             # optional, px (default 120)
  segments:
    - value: 57
      color: green
      label: "Enterprise"
    - value: 28
      color: primary
      label: "Mid-Market"
    - value: 15
      color: amber
      label: "SMB"

Values are percentages (should sum to ~100). Each segment gets a

display

field to override the legend value (e.g.,

display: "$5.8M"

instead of

"57%"

环形构成图——展示部分如何组成整体。

yaml

donut_chart:
  size: 120             # 可选，单位px（默认120）
  segments:
    - value: 57
      color: green
      label: "企业业务"
    - value: 28
      color: primary
      label: "中端市场"
    - value: 15
      color: amber
      label: "SMB"

数值是百分比（总和应该约为100）。每个分段可设置

display

字段覆盖图例值（例如用

display: "$5.8M"

代替

"57%"

）。

Line Chart

折线图

SVG-based trend chart — shows change over time.

yaml

line_chart:
  height: 120           # optional, px (default 120)
  lines:
    - label: "Revenue"
      color: green
      points: [3.2, 4.8, 6.8, 10.2]
    - label: "Costs"
      color: red
      points: [2.8, 3.4, 4.1, 5.2]
  x_labels: ["Q1", "Q2", "Q3", "Q4"]

Lines auto-scale to the data range. Multiple lines share the same scale. Set

fill: false

on a line to disable the subtle area fill.

基于SVG的趋势图——展示随时间的变化。

yaml

line_chart:
  height: 120           # 可选，单位px（默认120）
  lines:
    - label: "收入"
      color: green
      points: [3.2, 4.8, 6.8, 10.2]
    - label: "成本"
      color: red
      points: [2.8, 3.4, 4.1, 5.2]
  x_labels: ["Q1", "Q2", "Q3", "Q4"]

折线会根据数据范围自动缩放。多条折线共用同一个刻度。给折线设置

fill: false

可关闭淡色区域填充。

Summary Grid

摘要网格

Three-column grid of big numbers — works well on dark variant slides.

yaml

summary_grid:
  items:
    - value: "$10.2M"
      label: "ARR"
      color: green
    - value: "130%"
      label: "NRR"
      color: gold
    - value: "5.2x"
      label: "LTV:CAC"
  total:                  # optional bottom row
    label: "Near break-even"
    value: "$40K net burn"

三列大号数字网格——非常适合dark变体的幻灯片使用。

yaml

summary_grid:
  items:
    - value: "$10.2M"
      label: "ARR"
      color: green
    - value: "130%"
      label: "NRR"
      color: gold
    - value: "5.2x"
      label: "LTV:CAC"
  total:                  # 可选的底部行
    label: "接近盈亏平衡"
    value: "净消耗4万美元"

Quadrant Grid

四象限网格

2×2 grid — great for competitive analysis, SWOT, or categorized lists.

yaml

quadrant_grid:
  - title: "Strengths"
    bg: "#ecfdf5"
    border: "#a7f3d0"
    title_color: "var(--green-dark)"
    items:
      - "**Feature A** — 9-month head start"
      - "**API flexibility** — developers choose us 3:1"
  - title: "Weaknesses"
    bg: "#fff1f2"
    border: "#fecaca"
    title_color: "var(--red)"
    items:
      - "**Mobile** — no native app yet"

2×2网格——非常适合竞争分析、SWOT分析或分类列表。

yaml

quadrant_grid:
  - title: "优势"
    bg: "#ecfdf5"
    border: "#a7f3d0"
    title_color: "var(--green-dark)"
    items:
      - "**功能A**——领先9个月"
      - "**API灵活性**——开发者选择我们的比例为3:1"
  - title: "劣势"
    bg: "#fff1f2"
    border: "#fecaca"
    title_color: "var(--red)"
    items:
      - "**移动端**——暂无原生应用"

Actions

行动项

Numbered action badges with impact statements.

yaml

actions:
  - num: 1
    text: "**Ship the Growth tier** to reduce churn"
    impact: "Target: cut churn from 4.2% to 2.5%"
  - num: 2
    text: "**Double enterprise pipeline**"
    impact: "Target: $8M qualified pipeline"

带影响说明的编号行动徽章。

yaml

actions:
  - num: 1
    text: "**上线增长套餐** 降低流失率"
    impact: "目标：将流失率从4.2%降至2.5%"
  - num: 2
    text: "**企业客户线索翻倍**"
    impact: "目标：800万美元合格线索"

Raw HTML

原生HTML

Inject arbitrary HTML for custom layouts.

yaml

html: |
  <div style="display:grid;grid-template-columns:1fr 1fr 1fr;gap:20px;">
    <div style="padding:16px;border-radius:8px;background:rgba(255,255,255,0.06);">
      <div style="font-weight:600;">Custom content</div>
    </div>
  </div>

注入任意HTML实现自定义布局。

yaml

html: |
  <div style="display:grid;grid-template-columns:1fr 1fr 1fr;gap:20px;">
    <div style="padding:16px;border-radius:8px;background:rgba(255,255,255,0.06);">
      <div style="font-weight:600;">自定义内容</div>
    </div>
  </div>

Layouts

布局

Columns

分栏

Two-column or three-column layouts:

yaml

- title: "Revenue Breakdown"
  layout: cols              # or cols-3
  layout_style: "grid-template-columns: 3fr 2fr;"  # optional custom widths
  columns:
    - card: "Left Card"
      table: { ... }
    - content:
        - callout: { ... }
        - callout: { ... }

Each column can be:

A card (has
```
card
```
key) — rendered with border, background, padding
A content stack (has
```
content
```
key) — vertical flex layout
A direct component — table, callout, etc. directly on the column

两栏或三栏布局：

yaml

- title: "收入拆分"
  layout: cols              # 或者 cols-3
  layout_style: "grid-template-columns: 3fr 2fr;"  # 可选自定义宽度
  columns:
    - card: "左侧卡片"
      table: { ... }
    - content:
        - callout: { ... }
        - callout: { ... }

每个分栏可以是：

卡片（含
```
card
```
键）——渲染为带边框、背景、内边距的容器
内容栈（含
```
content
```
键）——垂直弹性布局
直接组件——表格、标注框等组件直接放在分栏里

Cards

卡片

Cards wrap content in a styled container:

yaml

- card: "Card Title"        # title shown as small uppercase label
  style: "..."              # optional card CSS
  table: { ... }            # any component(s)
  content:                  # or a content array
    - callout: { ... }
    - stat_boxes: [...]

卡片将内容包裹在带样式的容器中：

yaml

- card: "卡片标题"        # 标题显示为小写字样标签
  style: "..."              # 可选的卡片CSS
  table: { ... }            # 任意组件
  content:                  # 或者内容数组
    - callout: { ... }
    - stat_boxes: [...]

Themes

主题

Themes are YAML files in the

themes/

directory. The theme specified in

meta.theme

is loaded automatically.

Built-in themes:

aurora

navy

terracotta

wine

demo-teal

For creating custom themes, read

references/themes.md

主题是存放在

themes/

目录下的YAML文件。

meta.theme

中指定的主题会自动加载。

内置主题：

aurora

、

navy

、

terracotta

、

wine

、

demo-teal

。

要创建自定义主题，可阅读

references/themes.md

。

Logo

Logos are defined in the theme and appear automatically on every slide. They use

currentColor

in SVG so they adapt to light/dark variant backgrounds.

yaml

undefined

Logo在主题中定义，会自动显示在每张幻灯片上。SVG格式的Logo使用

currentColor

，所以会适配浅色/深色变体背景。

yaml

undefined

Icon logo with company name text:

带公司名称文字的图标Logo：

logo: svg: '<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">...</svg>' text: "Company Name"

logo: svg: '<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">...</svg>' text: "公司名称"

Wordmark logo (wide text-based logo):

文字商标Logo（宽版文字类Logo）：

logo: style: "height:16px;" svg: '<svg viewBox="0 0 252 27" xmlns="http://www.w3.org/2000/svg">...</svg>'


The default logo height is 20px, suitable for square icon marks. For wordmarks, set `style` to control the height — the width scales proportionally. The logo renders at 35% opacity on light slides, 55% on dark — present but never competing with content. Position is top-right, aligned with slide padding.

logo: style: "height:16px;" svg: '<svg viewBox="0 0 252 27" xmlns="http://www.w3.org/2000/svg">...</svg>'


默认Logo高度为20px，适合方形图标。对于文字商标，可设置`style`控制高度，宽度会按比例缩放。Logo在浅色幻灯片上的不透明度为35%，深色幻灯片上为55%——可见但不会和内容抢注意力。位置在右上角，与幻灯片内边距对齐。

PDF Export

PDF导出

bash

npx lucida-slides pdf deck.slides.yaml --open

Produces a 16:9 PDF (1280×720px per page) with all backgrounds, colors, and gradients preserved. Requires Playwright with Chromium — install once:

bash

npx playwright install chromium

bash

npx lucida-slides pdf deck.slides.yaml --open

生成16:9比例的PDF（每页1280×720px），保留所有背景、颜色和渐变效果。需要安装带Chromium的Playwright，执行以下命令一次性安装：

bash

npx playwright install chromium