日本語

Calendar Slides

Build slides whose axis is the calendar itself, from dated tasks and events. The date arithmetic — weekday offsets, 4–6 week rows, holidays, bars that wrap across weeks, working-day counts, page splits — lives in scripts/calendars.py and scripts/calendar_pages.py. Never compute calendar coordinates by hand.

Run everything from the slide-forge root with .venv/bin/python. Follow references/workflow-contract.md for the deck lifecycle (approve → validate → generate → QA → deliver).

Boundaries

Templates

Choose with form-selection.md. The limits and their derivation are in capacity.md. Primitive arguments are in references/calendars.md.

Workflow

1. Intake

Ask in one round, only for what is missing:

• the message: what should the reader conclude (the governing title, ≤ 36 full-width characters, one line);
• the period (start / end, or months);
• the data: pasted table, CSV, Google Sheet, or an existing document. Google Calendar is not imported automatically yet — ask the user to export or paste;
• week start (default mon; sun when the audience expects a wall calendar);
• company closures beyond national holidays (year-end, summer shutdown);
• the as-of date (today highlight and the source line);
• deck context: standalone pages or part of a larger deck; master template; QA (default: run).

2. Normalize

Write out/<deck>/calendar-data.json in the calendar_pages.py input format (see its docstring). Rules:

• Dates are YYYY-MM-DD (or YYYY/M/D). A date without a year is asked about, never guessed. Relative dates ("来週水曜") are resolved with the user.
• month-calendar events: [start, end, title, category, time]; empty end for a one-day item. Category is primary / success / danger / info / warning / muted or empty.
• daily-gantt rows: ["group", name, "", "", "", 0], ["task", name, owner, start, end, progress 0–1], ["milestone", name, owner, date, "", 0].
• daily-agenda items: [date, task, owner, due, status]; status is 完了 / 進行中 / 予定 / 遅延 / 中止 (or done / doing / todo / late / cancelled).
• weekly-timetable events: [date, start HH:MM, end HH:MM, title, place, category].
• sprint-calendar sprints: [number, goal, release true/false], with start on a Monday and lengthDays 7 or 14.
• year-at-a-glance marks: [start, end, label, busy|off|key] from startMonth.
• deadline-countdown: label, deadline, today (required), up to three checkpoints [date, name].
• activity-heatmap values: [date, number ≥ 0], one per day; leave missing days out instead of writing 0. source must state period, definition and unit.
• shift-roster people: [name, schedule] with one code character per day; codes: [code, label, colour, counts]; minStaff from the staffing standard.
• Keep plan and actuals apart; progress needs an as-of date in source.

3. Split and approve

.venv/bin/python scripts/calendar_pages.py out/<deck>/calendar-data.json \
    --out out/<deck>/pages/200-calendar.json

Show the page count, each page's period, and each title. A generated "（1/3）" suffix is a placeholder: propose a real message per page (pass them as titles). Get approval before generating.

4. Validate and generate

Combine with the rest of the deck when needed (scripts/assemble_spec.py), then:

.venv/bin/python scripts/build_deck.py --template templates/blank-16x9.json \
    --spec out/<deck>/deck.json --dry-run --strict
.venv/bin/python scripts/drive_folder.py create "<deck title>"
.venv/bin/python scripts/build_deck.py --template templates/blank-16x9.json \
    --spec out/<deck>/deck.json --title "<deck title>" --folder <FOLDER_ID>

Calendar pages use the BLANK layout and palette tokens, so any registered master works in place of blank-16x9.json. A primitive error (date outside the period, too many rows, unknown status) stops the dry run — fix the data, not the template. Upload calendar-data.json and the spec to the folder.

5. Visual QA

Run slide-qa. Calendar-specific checks: the day/column the "+N件" belongs to, bars split at week rows with "（続き）", Saturday blue / Sunday-holiday red, holiday shading not hiding bars, captions not colliding with the today line, and the title staying on one line.

6. Report

Deck and folder URLs, pages and periods, any year outside the bundled holiday data (the scripts print a warning), QA result and cleanup.

Maintaining the calendar pack

Schema, validation, registration and compatibility follow slide-template-creator. In addition:

1. Dates in, coordinates out. Slots take ISO strings; all calendar math is in calendars.py pure functions (unit-tested in tests/test_calendars.py). Add a pure function and a test before drawing with it.
2. Double the guard. Slot limits keep the example audit clean; the primitive raises ValueError for input that would be unreadable (rows too short, period too long, date outside the period). calendar_pages.py must split at the same limits — change both together.
3. Boundary inputs every change must pass (tests/test_calendars.py covers them): a 4-row month (2027-02, Monday start), 6-row months (2026-08), Sunday start, a bar wrapping a week and a month, "+N件" in a cell with a bar, a 31/60/61-day gantt, a 26-week gantt with year-end closures, an agenda with a collapsed holiday run, and the longest title.
4. Holidays. Never hand-edit assets/holidays/jp.csv; run scripts/update_holidays.py (yearly, after the Cabinet Office publishes the next year's equinox days in February).
5. Validate validate_slide_templates.py --pack calendar, the unit tests, and — when a shared primitive changed — every pack. Then generate the catalog (build_slide_template_catalog.py --pack calendar), run slide-qa, and refresh references/images/slide-templates/<id>.png and the catalog doc.

All nine forms of the plan (references/calendar-template-plan.md) are built; its §9–§11 carry the per-form status. Nothing here requires reading it.

Safety

• Calendars often carry people's names and private appointments. Keep real data under ignored out/ paths; examples use invented, role-based names.
• Do not present a plan as a commitment: the source line states the as-of date and that dates are planned.