Skip to content

Commit

Permalink
Containers to limit line length for reading
Browse files Browse the repository at this point in the history
  • Loading branch information
@Wolfr
Wolfr committed Apr 13, 2021
1 parent 78e6158 commit 57165b7
Show file tree
Hide file tree
Showing 2 changed files with 90 additions and 86 deletions.
86 changes: 44 additions & 42 deletions src/routes/styleguide/dev-notes/css-architecture.svelte
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,49 +10,51 @@
<title>{pageTitle} - Dev notes - JUI</title>
</svelte:head>

<div class="c-content">
<h2>CSS Architecture</h2>
<div class="u-spacer-top u-spacer-bottom">
<p>This project's CSS architecture uses a combination of the BEM naming convention and the Inverted Triangle CSS architecture in order to have a maintainable, readable and scalable code structure.</p>
<h3>BEM</h3>
<p>BEM stands for Block Element Modifier and it categorizes the code into three groups:</p>
<ul>
<li>Blocks which are a standalone entities that are meaningful on their own, for example <code>.c-menu</code>.</li>
<li>Elements which are part of a block and have no standalone meaning and are semantically tied to a block, for example <code>c-menu__item</code>.</li>
<li>Modifiers which are variants or flags on a block or element and are used to change the appearance or behavior, for example <code>c-menu--disabled</code>.</li>
</ul>
<p>The BEM naming convention helps to see how classes are related to each other.</p>
<p>For more information about BEM, please refer to this <a href="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/">excellent article</a> by Harry Roberts.</p>
<h3>Namespacing and ITCSS</h3>
<p>This project's CSS architecture uses namespacing. This means that every class in the codebase is prefixed with a certain string to explain what the code does and to avoid style leakage.</p>
<p>The namespaces are also used to separate the code base into different layers and this is where ITCSS comes into place.</p>
<p>The different layers that you find within the ITCSS architecture are, in the following order:</p>
<ul>
<li>
<strong>Settings</strong>,which are used with preprocessors and contain font, colors variables.
</li>
<li>
<strong>Tools</strong>, which is a layer used for mixins and functions.
</li>
<li>In the <strong>generic</strong> layer you can find ground-zero styles like resets, normalize styles and box-sizing.</li>
<li>
<strong>Base Elements</strong> which styles bare, unclassed HTML elements to redefine the default styling from browsers.
</li>
<li>
<strong>Objects</strong>, which is a layer used for undecorated design patterns, it is prefixed with <code>o-</code>.
</li>
<li>
<strong>Components</strong>, which is used to style specific UI components, here you will find the majority of the code and classes within this layer are prefixed with <code>c-</code>.
</li>
<li>
<strong>Utilities</strong>, which are helper and override styles and namespaced with <code>u-</code>.
</li>
</ul>
<p>The codebase is structured in this order so that it is ordered from generic to explicit styles, low-specificity to more specificity (ID selectors are avoided as much as possible) and far reaching to local styles, which makes the framework scalable and maintainable.</p>
<p>For more information on ITCSS, please refer to this <a href="https://speakerdeck.com/dafed/managing-css-projects-with-itcss">slideshow</a>.</p>
<div class="o-container o-container--medium">
<div class="c-content">
<h2>CSS Architecture</h2>
<div class="u-spacer-top u-spacer-bottom">
<p>This project's CSS architecture uses a combination of the BEM naming convention and the Inverted Triangle CSS architecture in order to have a maintainable, readable and scalable code structure.</p>
<h3>BEM</h3>
<p>BEM stands for Block Element Modifier and it categorizes the code into three groups:</p>
<ul>
<li>Blocks which are a standalone entities that are meaningful on their own, for example <code>.c-menu</code>.</li>
<li>Elements which are part of a block and have no standalone meaning and are semantically tied to a block, for example <code>c-menu__item</code>.</li>
<li>Modifiers which are variants or flags on a block or element and are used to change the appearance or behavior, for example <code>c-menu--disabled</code>.</li>
</ul>
<p>The BEM naming convention helps to see how classes are related to each other.</p>
<p>For more information about BEM, please refer to this <a href="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/">excellent article</a> by Harry Roberts.</p>
<h3>Namespacing and ITCSS</h3>
<p>This project's CSS architecture uses namespacing. This means that every class in the codebase is prefixed with a certain string to explain what the code does and to avoid style leakage.</p>
<p>The namespaces are also used to separate the code base into different layers and this is where ITCSS comes into place.</p>
<p>The different layers that you find within the ITCSS architecture are, in the following order:</p>
<ul>
<li>
<strong>Settings</strong>,which are used with preprocessors and contain font, colors variables.
</li>
<li>
<strong>Tools</strong>, which is a layer used for mixins and functions.
</li>
<li>In the <strong>generic</strong> layer you can find ground-zero styles like resets, normalize styles and box-sizing.</li>
<li>
<strong>Base Elements</strong> which styles bare, unclassed HTML elements to redefine the default styling from browsers.
</li>
<li>
<strong>Objects</strong>, which is a layer used for undecorated design patterns, it is prefixed with <code>o-</code>.
</li>
<li>
<strong>Components</strong>, which is used to style specific UI components, here you will find the majority of the code and classes within this layer are prefixed with <code>c-</code>.
</li>
<li>
<strong>Utilities</strong>, which are helper and override styles and namespaced with <code>u-</code>.
</li>
</ul>
<p>The codebase is structured in this order so that it is ordered from generic to explicit styles, low-specificity to more specificity (ID selectors are avoided as much as possible) and far reaching to local styles, which makes the framework scalable and maintainable.</p>
<p>For more information on ITCSS, please refer to this <a href="https://speakerdeck.com/dafed/managing-css-projects-with-itcss">slideshow</a>.</p>

<h3>Svelte specific: Inline Svelte <code>&lt;style&gt;</code> usage</h3>
<p>Where appropriate, use Svelte's inline styles, for example for uncommon components. This way the main stylesheet gets less bloated.</p>
<h3>Svelte specific: Inline Svelte <code>&lt;style&gt;</code> usage</h3>
<p>Where appropriate, use Svelte's inline styles, for example for uncommon components. This way the main stylesheet gets less bloated.</p>

</div>
</div>
</div>
90 changes: 46 additions & 44 deletions src/routes/styleguide/dev-notes/technical-notes.svelte
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,47 +7,49 @@
<title>{pageTitle} - Dev notes - JUI</title>
</svelte:head>

<RichContent>
<h2 id="technical-notes">Technical notes</h2>
<p>For those who are curious, here is the technical reasoning behind the way this framework is set up.</p>
<h3 id="compilers">Compilers</h3>
<ul>
<li>We use Svelte and Sass, both of which are compilers. This means we can pre-calculate as much as possible and we avoid calculating things on the client</li>
</ul>
<h3 id="sveltekit">SvelteKit</h3>
<ul>
<li>Using the power of Sveltekit, we can have an SPA, SSR or static site</li>
<li>Next to this we have the power of adapaters to easily deploy to Netlify, Vercel etc.</li>
</ul>
<h3 id="component-composition-strategy">Component composition strategy</h3>
<ul>
<li>Svelte is a compiler which can compile ahead of time, so there is no reason to minimize the amount of wrapper components</li>
<li>Having a set of wrapper components that can work in conjunction, allows us to specify a component API on top of them</li>
<li>We deliberately sometimes have more markup than needed for composition flexibility reasons, the ButtonInnerLayout and Toolbar components are good examples</li>
<li>We deliberately do not specify utility classes for flexbox, as I find building an API that mimics flexbox&#39;s API just leads to a plethora of classes that have a 1:1 relationship; not helping with anything.</li>
</ul>
<h3 id="css-strategy">CSS strategy</h3>
<ul>
<li><p>We use ITCSS to sort our CSS components</p></li>
<li><p>Sometimes, duplication is better than abstraction. To avoid tangling unrelated components, even if they share many similarities, code is duplicated (e.g. NavMenu vs SelectMenu)</p></li>
<li><p>We avoid using Svelte&#39;s style tag, so we can make use of consistent SCSS variables and have a way for variables to influence each other with a passthrough logic, something which CSS custom properties is not entirely ready for</p></li>
<li><p>When customizing this framework, I recommend throwing out all SCSS partials for components you do not use to minimize the final stylesheet</p></li>
<li><p>We use as much semantic HTML as possible</p></li>
<li><p>We use as much progressive enhancement that doesn&#39;t cause browser bugs</p>
<ul>
<li>This means that some level of PE is avoided where it is unclear what the global support is for said logic</li>
<li>The biggest reason for PE is screen reader usage</li>
</ul>
</li>
<li><p>We use BEM for components to make it clear which components belong together e.g.</p>
<pre class="c-pre"><code>&lt;ul class=&quot;c-pill-list&quot;&gt;
&lt;li class=&quot;c-pill-list__item&quot;&gt;
&lt;span class=&quot;c-pill c-pill--default&quot;&gt;
&lt;/li&gt;
&lt;li class=&quot;c-pill-list__item&quot;&gt;
&lt;span class=&quot;c-pill c-pill--default&quot;&gt;
&lt;/li&gt;
&lt;/ul&gt;</code></pre>
</li>
</ul>
</RichContent>
<div class="o-container o-container--medium">
<RichContent>
<h2 id="technical-notes">Technical notes</h2>
<p>For those who are curious, here is the technical reasoning behind the way this framework is set up.</p>
<h3 id="compilers">Compilers</h3>
<ul>
<li>We use Svelte and Sass, both of which are compilers. This means we can pre-calculate as much as possible and we avoid calculating things on the client</li>
</ul>
<h3 id="sveltekit">SvelteKit</h3>
<ul>
<li>Using the power of Sveltekit, we can have an SPA, SSR or static site</li>
<li>Next to this we have the power of adapaters to easily deploy to Netlify, Vercel etc.</li>
</ul>
<h3 id="component-composition-strategy">Component composition strategy</h3>
<ul>
<li>Svelte is a compiler which can compile ahead of time, so there is no reason to minimize the amount of wrapper components</li>
<li>Having a set of wrapper components that can work in conjunction, allows us to specify a component API on top of them</li>
<li>We deliberately sometimes have more markup than needed for composition flexibility reasons, the ButtonInnerLayout and Toolbar components are good examples</li>
<li>We deliberately do not specify utility classes for flexbox, as I find building an API that mimics flexbox&#39;s API just leads to a plethora of classes that have a 1:1 relationship; not helping with anything.</li>
</ul>
<h3 id="css-strategy">CSS strategy</h3>
<ul>
<li><p>We use ITCSS to sort our CSS components</p></li>
<li><p>Sometimes, duplication is better than abstraction. To avoid tangling unrelated components, even if they share many similarities, code is duplicated (e.g. NavMenu vs SelectMenu)</p></li>
<li><p>We avoid using Svelte&#39;s style tag, so we can make use of consistent SCSS variables and have a way for variables to influence each other with a passthrough logic, something which CSS custom properties is not entirely ready for</p></li>
<li><p>When customizing this framework, I recommend throwing out all SCSS partials for components you do not use to minimize the final stylesheet</p></li>
<li><p>We use as much semantic HTML as possible</p></li>
<li><p>We use as much progressive enhancement that doesn&#39;t cause browser bugs</p>
<ul>
<li>This means that some level of PE is avoided where it is unclear what the global support is for said logic</li>
<li>The biggest reason for PE is screen reader usage</li>
</ul>
</li>
<li><p>We use BEM for components to make it clear which components belong together e.g.</p>
<pre class="c-pre"><code>&lt;ul class=&quot;c-pill-list&quot;&gt;
&lt;li class=&quot;c-pill-list__item&quot;&gt;
&lt;span class=&quot;c-pill c-pill--default&quot;&gt;
&lt;/li&gt;
&lt;li class=&quot;c-pill-list__item&quot;&gt;
&lt;span class=&quot;c-pill c-pill--default&quot;&gt;
&lt;/li&gt;
&lt;/ul&gt;</code></pre>
</li>
</ul>
</RichContent>
</div>

0 comments on commit 57165b7

Please sign in to comment.