GoodLadTom/navaigate-present

What does navaigate-present do?

Interactive presentations in the member's own brand. The skill ships with no brand and no house style. Every deck looks like the member's brand, never like NavAIgate's. Before the first deck, it finds the style they want: it asks, researches their site and the sites they love, and shows them directions to choose from.

What every deck keeps, whatever the brand:

• One idea per screen. The words sit on the left: a label, a headline that lands word by word with one accent phrase, and a short plain paragraph. A live canvas demo sits on the right.
• The demo teaches by doing. The presenter presses, drags or switches one thing, and the screen answers at once: numbers count, charts redraw, cards glide to new places. Every change is eased, so nothing jumps.
• Nothing is ever dead. Each demo replays its arrival when its slide comes into view, and keeps some gentle movement while it waits. The page background moves slowly and ripples where you click.
• It runs like a talk. The down arrow (or Space, Page Down or the right arrow) moves exactly one slide. Up and left go back, and Home and End jump to the ends. F is full screen. Grouped progress runs along the bottom, the top bar names the slide, and a map slide jumps anywhere. This comes from template\core.js: never change it in a slide.
• It's tested like a film. Every slide is screenshotted at three sizes and every control is pressed. Nothing overlaps, clips or throws an error.

Speak plainly: most members aren't programmers. Say what's happening in one line before each step, and keep the commands to yourself unless they ask. Their brands live in their own folder, ~/.navaigate-present/brands/, so updating this skill never touches them.

0. Which brand?

Run python -I scripts\brand.py list.

• No brands yet, or they want a new one: do setup (sections 1 to 4) first. It takes about 15 minutes.
• One brand: use it. Several: ask which one, unless the request makes it obvious.

1. Questions

Tell them what's about to happen: a few questions, a look at their website and the styles they like, then two or three directions to choose from. Ask with AskUserQuestion (one call, four questions):

1. How should it feel? Calm and premium / Bold and energetic / Friendly and warm / Clean and technical.
2. Light or dark? Light / Dark / Match my website / Show me both.
3. Corners on buttons and tags? Fully rounded (pills) / Softly rounded / Square / Match my website.
4. Background behind the slides? A soft dot grid / A fine lattice / Graph-paper lines / Plain.

Then ask in the chat, in one message:

• the brand's name and website;
• the logo (a file path, or drag it in). SVG is best, otherwise a PNG with a transparent background. Say it can come from the website if they don't have the file;
• brand guidelines if they have them (a PDF or a link);
• one to three styles they love: websites, presentations, brands or screenshots, even from other industries. Say it can be anything they'd like their slides to feel like;
• anything they never want to see (for example pills, emojis or neon);
• who the presentations are for, in a line;
• where to save decks (suggest a <Brand> presentations folder in their Documents).

2. Research

1. Their site and their favourites. Run python -I scripts\research.py "~/.navaigate-present/research/<slug>" <their website> <each reference>. For each site it saves a screenshot of the first screen and of the page, and any logos it finds in the header. It also measures the fonts, background and text colours, accent colours, corners and label style that the page really uses. Look at every screenshot. The numbers say what's there, and the pictures say how it feels.
2. Their guidelines, if they sent them. Read the PDF: its colours, fonts and rules beat anything a website shows.
3. No website and no favourites? Search the web for three or four well-designed sites in their field and research those, for inspiration only. If Firecrawl is connected, firecrawl_search finds them, and scraping with formats: ["branding"] gives a second read of a site's colours and fonts.
4. Tell them what you found, in plain words and a few lines. For example: "Your site uses a deep green on cream, with a serif for headings. The deck you love is dark and uses square corners and a lot of space."

What to take from a favourite: its feel (light or dark, how much space, the type's character, corners, how much colour). Never take its logo, product names, words or exact layout. The member's own colours, logo and name stay theirs.

3. Directions

Make two or three draft brands in ~/.navaigate-present/drafts/<slug>-a, -b and -c. Each gets a brand.json (see references\BRAND.md), a copy of the logo, and a "direction" name of a few words. For example:

• A, true to your brand: their own site's colours, fonts and corners.
• B, closer to : their colours and logo, with the favourite's mode, type character, corners and background.
• C, an alternative: a clear contrast, such as dark if A is light, or a different type pairing. It must still be on brand.

Follow their answers: the feel, light or dark, the corners and the background. Where they said "match my website", use what the research measured. Then:

1. Run python -I scripts\brand.py check <draft folder> for each, and fix every PROBLEM line.
2. Run python -I scripts\brand.py compare <draft a> <draft b> [<draft c>]. It builds the opening and a chart slide in each direction and lays them side by side in one picture, directions.png.
3. Show them the picture and the full path of each direction's index.html, so they can press through it. Ask which one they like, or what to mix ("A's colours with B's type"). Adjust and compare again until one is right.

4. Save the brand

1. Write the chosen direction, with their changes, to ~/.navaigate-present/brands/<slug>/ (brand.json, logo and any font files).
2. Run python -I scripts\brand.py check <slug>, then python -I scripts\brand.py sample <slug>. That builds all five example slides in the brand and screenshots them.
3. Show the contact sheet and give the full path of the sample's index.html. When they're happy, setup is done, and every future deck uses this brand.

5. Making a deck

1. Brief. Who it's for, what they must leave with, roughly how many slides, where it's shown, and the facts it may use. Use only facts the member gives you or that you can source. Never invent a feature, a figure or a quote.
2. Outline. Run python -I scripts\new_deck.py "<deck folder>" "<title>" <brand slug>. It starts the deck with the example slides. Then write _build\deck.json: the groups (they become the progress bar) and the slide order. For each slide, decide the one thing the presenter will press and what it proves. A slide with nothing to press is a weak slide.
3. Copy. Write every slide's label, headline, hl and body in one pass, so the deck has one voice, in the brand's voice from brand.json. Headlines are 5 to 10 words, with hl (2 to 4 words) inside the headline. Bodies are about 45 words at most. Plain words and short sentences, with no em dashes and no "leverage", "seamless" or "unlock". If the writing-style and humanizer skills are installed, use them.
4. Build. Build each slide to references\SLIDE-BUILDER.md. Slides are separate folders, so helpers can build them in parallel. Give each helper that runbook, its slide ids, the brand slug, the facts and one demo idea per slide.
5. Test. Run python -I scripts\build.py "<deck>", then python -I scripts\shoot.py "<deck>" 1920 1080, then the same at 1440 900 and 1280 720. Each run must print missing copy: none, fit: clean and console: clean. Look at every screenshot, including the ones taken after each control is pressed.
6. Review. Read each slide as the audience would. Does the demo prove the headline? Are the words plain and true? Do the sample figures add up, and are they labelled "Example figures"? Check the brand's never list.
7. Deliver. Give the full path of the deck's index.html. It's one file that works offline, apart from Google Fonts, plus assets\ if a slide loads images.

Rules

• Colours and fonts come only from the brand. In CSS use the tokens (--accent, --accent-ink, --s1, --text, --muted, --line and the rest). In canvas use E.COL and E.FONT, E.HEAD and E.LABEL. Never type a hex colour into a slide: that's what lets one slide work in every brand.
• Accent words use --accent-ink (or E.COL.accentInk), the accent adjusted until it reads on the background. Fills use --accent, and words on an accent fill use --on-accent.
• Corners follow the brand. Use var(--rp) for buttons and tags, var(--r) for cards, and E.R in canvas. Never type 999px.
• The logo is always the member's real file, inlined by the build (<!--LOGO--> in a section). Never redraw it, and never ask an image generator for it. With no logo file, the brand's name is set in its headline font. Give a logo a fixed box and fit it inside (object-fit: contain).
• Figures are real or labelled. Sample maths must add up and say "Example figures".
• Money and numbers use the brand's locale and currency (E.money, E.num). The language is the brand's (British English by default).

Files

• template\page.html: the shell and the whole CSS design system, all in brand tokens.
• template\engine.js (E): the drawing kit (curves, cards, text, labels, cursor, ripple, ticks, smooth chart lines, grids, money, the backgrounds).
• template\core.js (P): copy, the word-by-word headline, stages, keyboard and progress, controls, the loop.
• scripts\research.py: screenshots and measures websites.
• scripts\brandkit.py: turns brand.json into tokens, fonts and the logo, contrast-checked.
• scripts\brand.py: list, check, compare and sample brands.
• scripts\new_deck.py starts a deck, scripts\build.py builds one, and scripts\shoot.py tests one.
• references\BRAND.md: the brand.json format. references\SLIDE-BUILDER.md: the slide contract and demo rules (give it to every helper).
• examples\slides\: start (the logo reveal), path (the map), idea (sliders driving a chart), switch (a before-and-after that rearranges) and close. They're the standard every new slide must match.

Lessons already learned

• </script anywhere in inlined code, even in a comment, ends the page's script early. build.py escapes it.
• A range input's step must land on its default value, or the browser snaps it to the nearest step.
• A logo given only a width and a max-height overflows its box, and the reveal's mask then cuts it off. Give it a width and a height, and fit it inside.
• Controls that shoot.py presses must never be truly disabled. Use aria-disabled="true" instead.
• Some Google fonts lack weights (Space Mono has only 400 and 700). brand.py check finds the weights each font has and saves them.
• Many brands keep their buttons black and put the accent colour on words and icons. research.py looks there too, so read its accent list alongside the screenshots.
• Here-documents in a shell can eat backslashes and quotes. Write slide files and scripts with a file-writing tool.