langchain-evolution-deck/design-system.md

design-system.md

Гайд по lc-evo-deck/design-system.js для тех, кто собирает слайды.

Что внутри

design-system.js экспортирует единый объект с тремя слоями:

Слой	Что лежит
palette	Цвета: фон, текст, акценты, код, состояния
fonts	code, ui, fallback (Arial для кириллицы)
sizes	Шкала шрифтов: h1 ... caption, eyebrow
spacing	Отступы: page, card_pad, gap
layouts	Константы 16:9: HEADER_Y, CONTENT_TOP, CONTENT_BOTTOM, FOOTER_Y
theme	Все перечисленное выше в одном объекте (удобно пробрасывать)
helpers	Готовые функции для сборки слайда

Импорт:

const ds = require('./design-system');
const { theme, helpers, layouts } = ds;

Геометрия слайда (16:9, дюймы)

y=0.00  +-----------------------------------------------+
        |  HEADER_Y = 0.4                               |
        |    eyebrow (10pt, accent)                     |
y=1.25  |  --- hairline ---                            |
        |  CONTENT_TOP = 1.4  <-- начинай контент тут   |
        |                                               |
        |  контент                                       |
        |                                               |
y=5.05  |  CONTENT_BOTTOM = 5.05                       |
        |  FOOTER_Y = 5.25  <-- page number, source    |
y=5.625 +-----------------------------------------------+
        x=0.5                                      x=9.5
        ^ отступ `spacing.page` (0.5 дюйма) с обеих сторон

Минимальный слайд

const pptxgen = require('pptxgenjs');
const ds = require('./design-system');
const { theme, helpers, layouts } = ds;

const pres = new pptxgen();
pres.layout = 'LAYOUT_16x9';

const slide = pres.addSlide();
helpers.slideBase(slide, pres, theme);
helpers.addHeader(slide, pres, theme, {
  section: 'Stage 2: Chains',
  sectionNumber: 2,
  title: 'LCEL: composable expressions',
  eyebrow: 'STAGE 2',
});
helpers.addPageNumber(slide, pres, theme, 1);

await pres.writeFile({ fileName: 'lc-evolution.pptx' });

Какой layout для какого случая

Слайд	Что использовать
Титул раздела / stage divider	helpers.addSectionDivider (большая цифра + заголовок)
Текст + код	addHeader + addCodeBlock слева, addCallout справа
Сравнение двух подходов	addProsCons (две колонки, + и -)
Цитата / важное замечание	addCallout с `kind: 'info'
Код с акцентом на строке	addCodeBlockWithHighlight + lines: [3, 4]
Источник внизу	addSourceLine
Любой слайд	addPageNumber в правом нижнем углу

Helper-функции -- короткая справка

slideBase(slide, pres, theme)

Закрашивает фон bg.primary. Вызывай первым на каждом слайде.

addHeader(slide, pres, theme, opts)

• opts.eyebrow -- маленький caps-ярлык сверху (например STAGE 2: CHAINS)
• opts.section -- альтернатива eyebrow
• opts.sectionNumber -- крупная цифра справа (необязательно)
• opts.title -- h1

addCodeBlock(slide, pres, theme, opts)

• opts.code -- строка кода (\n для переносов)
• opts.filePath + opts.startLine -- подпись // path/to/file.py:1-12
• opts.highlightLines -- массив 1-based номеров строк, которые подсветить
• Если строк больше, чем влезает по высоте, внизу появится желтая плашка // note: snippet has N lines, card fits ~M -- уменьши fontSize или разбей сниппет.

addCodeBlockWithHighlight(slide, pres, theme, opts)

То же самое, но принимает lines: [3, 4] как алиас для highlightLines.

addCallout(slide, pres, theme, opts)

• opts.kind -- info | warning | success | danger
• opts.title -- необязательный заголовок внутри плашки
• opts.text -- основной текст

addProsCons(slide, pres, theme, opts)

• opts.pros -- массив строк
• opts.cons -- массив строк
• Плюсы слева (зелёная рамка), минусы справа (красная).

addPageNumber(slide, pres, theme, n)

Правый нижний угол, монохромный caption.

addSectionDivider(slide, pres, theme, opts)

• opts.number -- крупная цифра слева
• opts.title -- заголовок справа
• opts.eyebrow -- необязательный caps-ярлык
• opts.intro -- абзац под заголовком

addSourceLine(slide, pres, theme, opts)

• opts.source -- URL или короткая ссылка
• По умолчанию x=0.5, y=5.30, w=7.0

highlightPython(code) (опционально)

Если на машине стоит pygmentize (из пакета pygments), функция вернет массив { text, color } токенов. Если бинарника нет -- вернется один токен с дефолтным цветом и весь код отрисуется моноширинно. Используй, когда нужна попроцедурная подсветка поверх addCodeBlock.

Правила

1. Не вставляй em-dash (--) и en-dash (-) -- заменяй на -- и -.
2. Не используй Unicode-кавычки -- только ASCII " и '.
3. Не используй ... -- заменяй на ....
4. Шрифты -- всегда через helpers.withFallback(name), чтобы Arial был гарантированным фолбэком.
5. Цвета бери из palette.* -- не хардкодь hex в слайдах.
6. Геометрия -- через layouts.* константы.
7. Любой новый слайд начинается с slideBase(...).

Частые ошибки

Симптом	Причина	Фикс
Шрифт Arial вместо JetBrains Mono	PowerPoint не нашел шрифт	Установи JetBrains Mono в систему
Кириллица в коде рендерится квадратами	Нет фолбэка	Используй helpers.withFallback(t.fonts.code)
Код вылезает за карточку	Слишком много строк	Уменьши sizes.code или укороти сниппет
Header и контент перекрываются	Контент начинается выше CONTENT_TOP	Подними y до layouts.CONTENT_TOP
Плашка note: snippet has N lines	Сниппет не помещается	Разбей на 2 карточки или уменьши sizes.code