Icon assets + tokens + pattern

[tylersticka]

• Bring in icon assets
• Determine Twig integration strategy
• Display as story
• Basic CSS pattern
  • Document component

[tylersticka]

The Twig integration strategy portion of this has proven a bit more complicated than I was expected.

Below are all the options I've explored. I am currently leaning toward Option 4, but wanted to confirm with someone in @cloudfour/dev before proceeding in that direction.

The Problem

SVGs benefit from some manipulation before they are embedded in a document:

• XML attributes (xmlns) and other cruft that isn't necessary or helpful in an HTML5 document may be safely stripped.
• Attributes like class, role, etc. may need to be manipulated so an SVG element has appropriate presentation and semantics for different situations.

To enable those sorts of manipulations, we need to coordinate between the SVG files and the template engine. In our case, the engine is Twig.

There are two template engine wrinkles to consider:

• Storybook refreshes components on the client side, and neither Twig.js or Twing (the two most mature Twig implementations for JavaScript) expose included files that weren't explicitly requested to begin with. This means that {% include 'path/to/file.twig' %} works fine, but {% include filename_variable %} will not work because by the time filename_variable is evaluated in the client, Twig will have already finished compiling all the templates it thought it needed.
• By default, Twig doesn't like including files that don't end in .twig or .html.

Option 1: Inline SVG extensions for JavaScript and PHP

We could author or install a inlineSvg helper in both JavaScript and PHP that requests the source SVG from the file system, optimizes it and extends its attributes.

{{inlineSvg('path/to/svg', 'o-icon', {
  role: 'presentation'
})}}

Pros

• Familiarity: We do something similar currently.
• SVGs are inlined on demand, so no need for intermediary compilation or transformation steps.

Cons

• Requires a non-standard Twig extension.
• Even if we use an external resource for this extension, we will need to duplicate its functionality across two languages. This increases maintenance time and fragility between the two repositories.

Option 2: Custom Twig loader

Twig and the Twing library for JS both use a "loader" philosophy for resolving files. This means we can define custom logic for resolving things like includes.

This means that, in theory, we could dynamically generate templates from SVG files by iterating over them and providing an object of paths and template sources to Twig.

{% include '@svg/assets/icons/heart' with {
  class: 'o-icon',
  role: 'presentation'
} %}

Pros

• Uses existing include syntax.

Cons

• Requires separate transformations and configurations for JavaScript and PHP, which may increase maintenance time and fragility between the two repos.
• Include paths cannot be relative (I tried), so familiarity with how the paths work will be required.

Option 3: Manual Twig templates from SVGs

We could prepare our SVG resources as Twig templates from the get go. So instead of an icon.svg file like this:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
  ...
</svg>

We would instead add an icon.svg.twig file that we prepare beforehand like any other Twig template:

<svg viewBox="0 0 24 24" width="24" height="24"
  {% if class %}class="{{class}}"{% endif %}
  {% if role %}role="presentation"{% endif %}>
  ...
</svg>

Which you could then reference as you would any other partial:

{% include '../../assets/icons/heart.svg.twig' with {
  class: 'o-icon',
  role: 'presentation'
} %}

Or if we'd prefer, we could structure things a bit differently. For example, we could include all icons in the same file:

<svg viewBox="0 0 24 24" width="24" height="24"
  class="o-icon {{class}}"
  role="{{role | default('presentation')}}">
  {% if name == 'arrow-right' %}
    ...
  {% elseif name == 'arrow-left' %}
    ...
  {% elseif name == 'arrow-up' %}
    ...
  {% elseif name == 'arrow-down' %}
    ...
  {% endif %}
</svg>

{% include 'objects/icon.twig' with {
  name: 'arrow-left',
  role: 'img'
} %}

Pros

• Behaves exactly like any other Twig template.
• Freedom to structure assets however we want, potentially making some components more self-contained (see icon example above).
• Does not rely on any compilation or build steps.
• Does not require coordinated development between patterns and PHP/WordPress.

Cons

• SVG files are no longer able to be easily opened in graphic editors.
• SVG files can no longer be used in <img> elements, referenced via CSS, etc.
• "Templatizing" of SVGs is a manual process, which may become tedious.

Option 4: Compile Twig versions of all SVGs

We could automatically transform SVG assets into Twig versions, using SVGO to optimize and some light string manipulation to "templatize."

So before transformation, you might have a folder that looks like this:

src/assets/icons
├── attachment.svg
├── check.svg
├── close.svg
└── heart.svg

After transformation, the folder would look like this:

src/assets/icons
├── attachment.svg
├── attachment.svg.twig
├── check.svg
├── check.svg.twig
├── close.svg
├── close.svg.twig
├── heart.svg
└── heart.svg.twig

Those .twig files appear like they do in the previous option:

<svg viewBox="0 0 24 24" width="24" height="24"
  {% if class %}class="{{class}}"{% endif %}
  {% if role %}role="presentation"{% endif %}>
  ...
</svg>

And you could reference them like any other include:

{% include '../../assets/icons/heart.svg.twig' with {
  class: 'o-icon',
  role: 'presentation'
} %}

Pros

• Familiarity: We are using this technique on a client project.
• Behaves exactly like any other Twig template.
• Does not require manual build steps.
• Original assets are preserved and may be referenced via <img>, background-image, opened in graphics editors, etc.
• Does not require coordinated development between patterns and PHP/WordPress.

Cons

• Requires an additional build step in the pattern library.

[gerardo-rodriguez]

I am currently leaning toward Option 4

Thanks for a detailed breakdown, @tylersticka!

I think Option 4 is a very reasonable solution. 🙂

[Paul-Hebert]

Thanks for writing that up @tylersticka . Option 4 sounds like the easiest to maintain from my perspective