Demo Notes 11 18 19

Concepts

Review the background and "why" of Larva / problems it solves - see root README.

Core packages for building a theme:

• Patterns
• Larva CSS
• Larva Tokens
• Parser

Principles

• Close Enough – If a value from the Invision mock does not match what is provided by Larva, use what is closest from Larva, then discuss with tech lead and product manager to determine if it is close enough.
• Good Friction – If Larva makes it difficult to write the CSS you are trying to write, that is likely intentional. Find another way to approach the problem that is easier. g.g. highly specific grid layouts, nudging elements with transforms and positioning, hard-coding widths and heights.
• Slow Down – Larva forces you to slow down and think about the UI you are building. You will greatly benefit from pseudo-coding the markup and CSS, perhaps by printing the design and drawing on it, before diving into programming it.

Anticipated Pain Points

• It will all be frustrating the first sprint or two until you have built up a common base of patterns, and you have become familiar with the language and adapt your current habits that do not align with Larva. Then things will move faster, and you'll get it.
• Which CSS utilities are in Larva, which are in the theme (hopefully IntelliSense plugin will solve this).
• IE11 support / asset building with Sass map defaults for two sets of tokens on a single site.

Anticipated Pitfalls (things that result in one-offs)

• Reverting to styling semantic-named CSS. It might be tempting, but don't do it because everything will fall apart. You can, however, do that in scratch-pad.scss to figure out the programming, then move the solution into utilities and algorithms.
• Allowing WordPress/PHP to control markup. This is the worst anti-pattern in Larva. If you have markup that exists outside of Twig, then every template that includes that markup will have to be a one-offs. One-offs breed.
• Specificity. Any specificity more than one class should only come from specific CSS algorithms.
• Trying to add custom breakpoints, specifically min- and max-width. Larva does not support them. Everything should fit into pmc-breakpoint, and if it doesn't, discuss with tech lead and product manager.

Agenda

Editor setup

• Recommended editor is VSCode
• Create Workspace with cloned Larva repo and theme
• Install this VSCode extension for CSS class IntelliSense
• Open user settings and add these lines (via command palette: >Preferences: Open Settings (JSON))

"html-css-class-completion.includeGlobPattern": "/**/build/**/*.css",
"html-css-class-completion.enableEmmetSupport": true

• Open AMH theme in a separate editor window for reference and copy/paste.

Building UI

Before you start, review the design in detail and compare against what exists in AMH. Start with the smallest pieces, and name things before you build them. PLAN BEFORE YOU CODE. Then:

• Create a module directory and prototype file, or copy from AMH for a starter.
• Get it loading in Larva.
• Work through the design details, adding utilities where needed.
• Leverage scratch-pad.scss for prototyping.
• When the module design is ready, generate a test with npm run backstop -- test followed by npm run backstop -- approve
• When ready for back-end, npm run parser (demo parsing Larva patterns, then parsing project patterns) and create a controller.
• Then write JSON npm run write-json (refer to theme README for command to write JSON for specific prototype variants)
• Add stub for static template to controller:

// TODO: @Person, ready for BE.

$trending_stories_widget = PMC\Core\Inc\Larva::get_instance()->get_json( 'modules/trending-stories-widget.prototype' );

// BE overwrites object keys with real data here.

\PMC::render_template(
	sprintf( '%s/template-parts/patterns/modules/trending-stories-widget.php', untrailingslashit( CHILD_THEME_PATH ) ),
	$trending_stories_widget,
	true
);