DEV Community: Stanley Lim

🚀 Cirrus 0.8.0 launched!

Stanley Lim — Tue, 18 Feb 2025 16:02:09 +0000

Cirrus 0.8.0! Lots of under the hood changes that have been in the works for quite a long time, but very excited it is finally out. This is a very crucial step before resuming work on Cirrus Blocks.

Docs
Github

🎉 Features

Major rewrite of class generation system.
New utility mixins to replace old ones:
- generator.utility -> generator_v2.utility
- generator.utility-with-body -> generator_v2.utility-with-body
Class generator now supports class grouping via group:[pseudo] and group-[pseudo] CSS classes. These allow developers to use events on a parent element to affect the styles of child elements.

@include generator_v2.utility(
    $base-class-name: 'text',
    $class-value-pairs: (
        'blue': (
            'color': blue,
        ),
    ),
    $variants: (
        'group-hover'
    ),
    $generate-viewports: true,
    $override: '!important'
);

.group:hover .group-hover\:u-text-blue {
    color: blue !important;
}

...

<div class="group">
    <p>test</p>
    <div class="group-hover:u-text-blue">
        <p>this is blue on hover</p>
        <p>this is also blue on hover</p>
    </div>
</div>

Class generator now supports many more variants (pseudos):
- 'responsive',
- 'dark', 'light',
- 'reduce-motion',
- 'first-of-type',
- 'last-of-type',
- 'portrait', 'landscape',
- 'hover', 'group-hover',
- 'focus', 'group-focus', 'focus-visible', 'focus-within',
- 'active',
- 'visited',
- 'checked',
- 'disabled'

@include generator_v2.utility(
    $base-class-name: 'text',
    $class-value-pairs: (
        'blue': (
            'color': blue,
        ),
    ),
    $variants: (
        'dark',
        'hover',
        'reduce-motion',
        'group-hover',
        'group-focus',
    ),
    $generate-viewports: true,
    $override: '!important'
);

.u-text-blue {
    color: blue !important;
}

.hover\:u-text-blue:hover {
    color: blue !important;
}

.group:hover .group-hover\:u-text-blue {
    color: blue !important;
}

.group:focus .group-focus\:u-text-blue {
    color: blue !important;
}

@media screen and (min-width: 640px) {
    .sm\:u-text-blue {
        color: blue !important;
    }

    .sm\:hover\:u-text-blue:hover {
        color: blue !important;
    }

...

Update grid class utilities to support generation with viewports and modifiers b3be15f
Enable hover pseudo selector for v2 colors 839cd47
Add custom button behaviors for v1 color classes (only apply on button selectors and add hover behavior) d4a6b6a
Add cursor util classes 32e0897
Add tooltip--visible class to show tooltips outside of :hover and :focus 9b77f78
Add new pseudo-variants config with integration to existing class generation 459dbba

@use "cirrus-ext" with (
    $config: (
        pseudo-variants: (
            CLEARFIX: ('responsive', 'hover', ...),
            FLEX: ('responsive'),
            ...
        ),
    ),
);

🐛 Fixes

Remove unnecessary forward for cirrus-all build 3dfa6e6
Migrate to ESM for Gulp, update Gulp deps, update CI to use Node 20 3697dee
Fix left padding for form-ext inputs 6453943
Remove inconsistent padding for table header and footer th 3842fce
Fix incorrect class name and property for italic font util class 6591ca1
Remove extra letter spacing from all text elements 6cb8f76
Add missing viewport config entries ea038be
Add missing grid-row styles grid-rows-, grid-r-, grid-rs-, and grid-re- 1295016
Fix grid row column style c95fe41
Link font weight and color adjustments no longer apply on nested input elements a6b5e25
Remove background color from avatar when there is a child image element 7d4ea82
Fix text color with a tag and .btn class c1c7fa5
Remove button shadow on focus for .btn--disabled 867eeff
Fix broken tab styles, remove remaining hardcoded colors #330 bfa64c6

💥 Breaking Changes

New viewport syntax across all classes that support different viewports, unifying the fractured viewport system.
- The main difference from before is now all viewport modifiers will use the same syntax instead of inconsistent system from before. All classes that are meant to apply at a certain viewport size and above will be in the form of [sm|md|lg|xl]:classname. This will be the case for all classes whether it is for columns or utility classes.
- Below are the main syntax changes:
  - col-sm-1 -> sm:col-1 - column classes will all have the viewport modifier prefixed at the front.
  - col-6 -> md:col-6 - all column classes that did not have the modifier class must be prefixed with md: to get the same behavior as before. This is to address the confusing implicit behavior where a class like col-6 would have 50% width for md and above but 100% width for viewports below md.
  - u-block-md -> md:u-block - for all utility classes, the viewport modifier will be prefixed at the front.
Deprecated margin:1 rem 0; style for p, article, blockquote since it leads to unexpected behaviors for users 9bcda3a
Deprecating row.no-space classes 8e802f9
Update Modal class names for clarity 9da499f
Deprecated .modal.small 9da499f
Deprecating placeholder.scss 39e663b
Deprecated .title and .subtitle classes b07c76d
Deprecated viewports config in favor of using 'responsive' entry in pseudo-variant config 1f33d83

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

🚀 Cirrus 0.7.2 Released

Stanley Lim — Sat, 30 Dec 2023 17:21:39 +0000

Hey everyone!

Just released 0.7.2 for Cirrus. Check it out! This release adds fixes to a lot of user requested issues.

💎 Cirrus
📝 Documentation

What is Cirrus?

Cirrus is a component and utility centric SCSS framework
designed for rapid prototyping. I started this project back in late 2016, but never really wrote about it. The main reason why you should use it is if you need to proto-type a project ASAP with many pre-styled component classes. There's a lot of CSS frameworks already out there, but Cirrus comes with my (and those who contributed in the past) take on what a CSS framework should have and a distinct style.

Onto the Updates

🎉 Features

Link pseudo elements will now use currentColor instead of fixed link color bd9ab44
Buttons now completely support color modifier classes (background, text, and border). 5962ca4
Add px (1px) to default sizing system. 14970c4
Add 48 and 64 to default sizing system to close the gap with xs viewport. 31f80f0
Border color util classes will now set button shadow color, taking precedence over bg color classes. 46fcc01
Add new normal-case utility class. 81d36aa
Add vertical-align util classes. ee67b56
Update utility mixin to handle prefers dark/light and reduced motion variants. 4907381
Add common class name field to utility api, add new function to convert old class map to new class mapping for utility mixin. 3b6d753
Reorder style generation to minimize minified size with gulp-clean-css. b5dd955
Add new gap classes for row or column only 5c317e0
Add new font style classes #192 83463e1
Move language label for code component to styling for 'pre' #206 2248631
Add new helper class to toggle tree-nav visibility 623a19d
Integrate native hover color generation for buttons using bg- modifier classes 7b55b6d
Add new utility classes for grid auto flow row and column. f0349a1

🐛 Fixes

Remove margins from label HTML element. 010146f
Remove margins for btn-close. 4bfb7c0
Last border of accordion item should be invisible. a95694b
Add missing button variables to v1 color classes. 8e01988
Reset cursor of nav-item children. c706fce
Inline condition for generating classes to avoid conflicting variable names. 50dc1b5
Fix incorrect viewport being used to apply fill-height styles #163. 7ef825b
Add left text alignment for list in dropdown menu. 6997266
Fix horizontal centering for default spinner. 50af674
All semantic color references to _theme.scss will now use _config.scss for customization #174 d3e0f9a
Remove duplicate generation of blur util classes c60a237
Fix grid row support, grid rows will now have a max of 6 74cdab9
Remove extra padding on anchor tags 9bd4aec
Move pointer cursor to tag__close-btn specifically instead of colored tags #193 0a6c23f
Hide overflow for frame component #195 7fd9209
Restrict transition animation to only box shadow #194 4731e12
Fix specifier for tree-nav class for small viewports 875a5ce
Fix issue where range slider does not slide from start to end #217 77582e7
Fix accordion rendering on Safari #216 ab69a6c
Set pointer as default cursor for pagination-item a tag #211 d9ea857
Vertical center spinner fix (#242) 856461d
Fix bug where list dropdown menu flashes briefly during page load #207 2cbc17a
Use default browser focus styling for elements that don't have custom styling b164485
Remove unused focus styling 68eb3a2
Fix incorrect property used for column gap 81336a8
Fix bug where webkit default focus styles were applied instead of input, textarea, and select focus styles, refactor forms code cff0e97
Fix incorrect selector used in commit a95694b 7090712
Form border styling should respect --border-opacity var if present 95bb80b
Fix horizontal alignment of loading spinner f093e8f

💥 Breaking Changes

Rename tree-nav--shown to tree-nav--visible to follow new class conventions 37290af
Deprecate .menu-item.right, revert to applying list stylings to child link to support nested lists, expand list stylings to child divs and spans first children only #198 889f0fe
Deprecating .usquare and .usquare.delay classes due to incompatible color styling 161bf52

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

🚀Maximizing Efficiency and Impact - Why I choose Mermaid for Graph Creation

Stanley Lim — Tue, 20 Jun 2023 15:00:00 +0000

Before I talk about what Mermaid is and why you should use it, let's take a step back and discuss why diagrams are essential for engineers.

Why Diagram?

Diagrams are an invaluable resource for conveying ideas with clarity and ease. In software engineering, all facets of our work involve the transfer of information over different mediums to make informed decisions. Like slideshows and newsprint, readers tend to be more captivated by images and graphics over long walls of text. In design reviews, diagrams are used to represent complex system architectures and relationships from a birds-eye view. Engineers use these to effectively convey their vision. With large walls of text, readers can be more disengaged, causing them to haphazardly scan through the document. Logic errors, bottlenecks, and security risks that could have been caught in the design phase may one day wreak havoc on production.

Diagrams also play a pivotal role in documentation, where they serve as visual anchors for complex concepts. A boon to engineers old and new, diagrams depict structures that anyone can reference at any time. It fosters better understanding, easier knowledge transfer, and improved operations. The next someone asks you about where your team sits in a vast network of services, you can send them an image that depicts a high-level overview of your upstream and downstream callers.

One of the biggest problems with diagrams, like any other documentation, is that it presents an overhead, sometimes large, to engineers when they don't want to maintain it. The danger comes when engineers forget to update a diagram when changes occur, forget to include a diagram in the first place, or reference a stale diagram as the source of truth. These situations can result in extra engineering time to verify its validity, or worse, making the wrong decisions under incorrect assumptions. If left untouched for even longer, it will have overreaching impacts of slowing the ramp-up of new hires and the productivity of the team.

This is where Mermaid comes in, a lightweight diagramming and charting tool designed to tackle stale diagrams.

What is Mermaid?

Mermaid provides a lightweight syntax akin to Markdown for rendering all sorts of chart types. As of writing, Mermaid supports the following chart types:

Flowchart

Sequence Diagram

Class Diagram

State Diagram

Entity Relationship Diagram

User Journey

Gantt

Pie Chart

Quadrant Chart

Requirement Diagram

Gitgraph (Git) Diagram

C4C Diagram (Context) Diagram

Mindmaps

Timeline

Zenuml

The list above continues to grow with more functionality added each day. Because it is open-sourced, we can dig into issues and report/fix them ourselves if needed.

Mermaid is designed to make diagramming easier by taking away the cognitive load that comes with positioning boxes, drawing and styling arrows, and other details that don't necessarily make the diagram any clearer -- helping you get things done faster.

flowchart LR

A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

Some of the neat features it has include CSS class support and integration from any webpage straight from their CDN.

graph LR
    classDef terminal font-weight:bold,fill:#0066ff,color:white

    styled:::terminal
    unstyled

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
</script>

<pre class="mermaid">
    graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);
</pre>

Why Mermaid?

I wouldn't say this is a full-on replacement for heavier graphing applications like LucidChart, but it does solve some of the biggest problems with using these heavier tools. One of the biggest drawbacks of more involved diagramming tools is the amount of busy work that comes with it once you have a rough idea of what parts are needed. This is one reason that would cause people not to diagram in the first place.

Mermaid takes that overhead and tosses it out the window by making all diagrams powered by its JS library and its intuitive syntax. There is no need to export your diagram as an image or some proprietary, editable file format anymore as these diagrams are self-documenting. With the proprietary format, you can edit and view it, but only in an editor that supports that format. With images, anyone can view them, but you cannot edit them. With Mermaid's markup, anyone can easily edit yet understand what the graph is depicting with a simple text editor.

These diagrams are also immensely portable. They can live in your design docs or your source code. You can audit changes to the diagram via source control to know precisely what things have changed. For complicated visuals, engineers can pinpoint new lines, labels, etc. to make their comprehension faster.

Another reason to try Mermaid for your next diagram is the growing community and third-party integration. With growing support from platforms like Github's Markdown renderer, Google Docs, Jupyter, and more, anyone can easily get started with a diagram by typing a few lines of markup in their favorite SaaS. Today, you can find Mermaid powering Kubernetes's documentation throughout the entire website.

Mermaid rendering on GitHub.

Last but not least, the tooling is some of the easiest to get started with. Just hop onto mermaid.live to try Mermaid out yourself. The editor comes with:

Syntax highlighting
Live previews
Static URLs to share with others
Export as JPG, PNG, SVG, and more.

If the live editor is not your cup of tea, you can try out their CLI. With a simple command, you can convert a .mmd file to the format you want by specifying a couple of flags. Below is an example of generating an SVG from a Mermaid file with custom CSS:

mmdc --input test-positive/flowchart1.mmd --cssFile test-positive/flowchart1.css -o docs/animated-flowchart.svg

Closing Thoughts

Mermaid is a simple tool that takes away a lot of the overhead when it comes to creating diagrams. By eliminating the overhead associated with traditional diagramming software, Mermaid allows you to focus on content creation rather than struggling with complex tools. Its lightweight nature, intuitive syntax, and language-agnostic approach make diagramming a seamless and enjoyable experience. Moreover, Mermaid's integration with numerous third-party tools and platforms enhances its versatility and accessibility, allowing you to effortlessly incorporate captivating visualizations into websites, documentation, and other mediums. This is a tool I would gladly recommend the next time you are looking to diagram something.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on GitHub.

TIL How Casing Can Break Netlify Functions

Stanley Lim — Mon, 27 Feb 2023 15:00:00 +0000

Did you know Netlify Functions could break when renamed to the same name with a different casing? I sure didn't.

What are Netlify Functions?

If you know what AWS Lambda or GCP Cloud Functions are, then Netlify Functions won't be a stranger to you. Netlify functions are serverless functions powered by Netlify's infrastructure. These functions are designed to allow you and me to quickly build and deploy serverless applications without the need for managing infrastructure or scaling concerns.

One of the common ways we can use Netlify Functions is by serving API routes defined in frameworks like Next.js. Suppose I wanted to create some endpoints for my frontend application to call, like /api/toast/<id>. In that case, Next.js enables you to create your route within the same root directory under the /pages/api directory. You can read more about it here.

Is this a bug?

I have been toying around with Netlify Functions to test a few APIs here and there to see how easy it is to integrate into a project. Over time, one of the routes I defined stopped working on my live deployment. And the worst part was that it worked locally.

The route was a dynamic API route that took in an id called toastId so I can fetch a piece of Toast by id (this is a simple test app, don't worry about it).

export default async (req: NextApiRequest, res: NextApiResponse) => {
  try {
    const { toastId } = req.query;
    // Fetch the piece of toast by id and do something with it...
  } catch (ex) {
    // ...
  }
};

Looking through the Git history to see what change may have broke, it didn't give too many hints as to how I broke it -- neither did logging out the value on my local deployment.

What did help was logging out the value on the deployed instance of my test app. Turns out, my renaming of the dynamic route file from [toastid].ts to [toastId].ts broke what I initially deployed to Netlify. When I ran the server locally, the casing change took effect as expected. However, it was not reflected when deployed to Netlify. As a result, my route was not able to extract the path parameter using the following code snippet:

const { toastId } = req.query; // `toastid` was being populated instead

After renaming the file from [toastId].ts to [toastid].ts, the route worked once more.

Now, is this a bug or just an undocumented behavior? Unfortunately, I have yet to find an answer for this in the Netlify and Next.js documentation or StackOverflow and Github Discussions. Please let me know if any of you do!

From my perspective, naming in the Windows file system is not case-sensitive, but many Unix systems are. I'm curious to know if this influenced their decision on how they handled names with different casing. One possibility is that they wanted to map all names regardless of casing to the same function to avoid things breaking when deployed by different developers running different operating systems. But that's just a thought.

Tl;dr

The name you choose for your routes in your Next.js app matters. It may not be apparent when you're working on it locally, but quirks such as this one on Netlify can throw a wrench into your application deployed in prod.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

GoDaddy Redirect Hack

Stanley Lim — Wed, 21 Dec 2022 14:00:00 +0000

Introduction

Over the last few days, website owners, specifically those hosting on GoDaddy, have been experiencing strange redirects to various websites. These redirects don’t happen all the time, but they seem to happen when a user first visits a page or refreshes it enough times to trigger it. I first stumbled upon this issue when visiting a website of a favorite restaurant of mine. Instead of seeing a page with pictures of food, menus, etc., I was presented with a fake AV page.

How it works

Like with other security issues I discover, I end up jumping down the rabbit hole to investigate what this is, how it works, and whether there is a way to avoid it. Unfortunately, for this incident, the best perspective I can give is as an outsider. A compromised GoDaddy website would make this investigation easier, but it isn’t impossible without it.

At a high level, the sequence of events is as follows based on testing and other observations:

1. The user visits a compromised website hosted on GoDaddy.

Like me, users could visit a local business’s website they are familiar with.

2. Initial redirect occurs

Through some black box logic (usually for first-time visitors or by chance), GoDaddy servers send a 302 to the user to redirect them to the attacker’s website. Every compromised website I’ve found redirects to 46.4.68.136.

Currently, there is speculation that GoDaddy’s load balancers are compromised. Specific requests will redirect you to the attacker’s page, but this occurs less often than expected. The cached versions of these compromised sites show a redirect in the HTTP response’s header. This header will cause the browser to redirect to the website specified in the path variable. Below are some examples.

HTTP/1.1 302 Found
Date: Fri, 16 Dec 2022 22:23:24 GMT
Server: Apache
P3P: CP="NOI ADM DEV PSAi COM NAV OUR OTRo STP IND DEM"
Cache-Control: no-cache
Pragma: no-cache
Set-Cookie: b64618f79bd8f79428b7f1f80c1abceb=qtjmovs3948hi5t1m2shhambr4; path=/
Location: http://46.4.68.136/[REDACTED]?DOM=www.vocationalvisions.com&URI=%2findex.php
Connection: close
Vary: Accept-Encoding
Content-Type: text/HTML; charset=utf-8

HTTP/1.1 302 Found
Date: Sat, 17 Dec 2022 17:21:14 GMT
Server: Apache
X-Pingback: http://www.bookkeepingservicesclt.com/xmlrpc.php
Location: http://46.4.68.136/[REDACTED]?DOM=www.bookkeepingservicesclt.com&URI=%2findex.php
Connection: close
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

HTTP/1.1 302 Found
Date: Fri, 16 Dec 2022 14:43:04 GMT
Server: Apache
Location: http://46.4.68.136/[REDACTED]?DOM=www.daria-snadowsky.com&URI=%2findex.php
Connection: close
Vary: Accept-Encoding
Content-Length: 0
Content-Type: text/html; charset=UTF-8

HTTP/1.1 302 Found
Date: Tue, 13 Dec 2022 14:00:31 GMT
Server: Apache
X-Powered-By: PHP/5.6.40
Link: <http://saslist.com/wp-json/>; rel="https://api.w.org/"
Location: http://46.4.68.136/[REDACTED]?DOM=saslist.com&URI=%2findex.php
Connection: close
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

HTTP/1.1 302 Found
Date: Wed, 14 Dec 2022 00:20:15 GMT
Server: Apache
X-Powered-By: PHP/5.6.40
X-Pingback: http://paypointeinc.com/xmlrpc.php
Location: http://46.4.68.136/[REDACTED]?DOM=paypointeinc.com&URI=%2findex.php
Connection: close
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

These websites receive a response from an Apache-powered server and will redirect the user to the same malicious IP address -- whether they use WordPress or not doesn't play a factor.

Every user that ends up being redirected to the attacker's host is then tagged with a cookie set from the response header. Every subsequent request on that host will also include that cookie to identify the victim.

Set-Cookie: a8163=<JWT looking token>

3. The second redirect occurs

Redirect takes the user to a specific page on the attacker's website. This page then runs JavaScript to redirect them to phishing or pornographic content. The basic structure of the page we see is as follows:

<html>
        <head>
            <script type="application/javascript">
                function process() {
                   if (window.location !== window.parent.location ) {
                      top.location = "http://bad.website";
                   } else {
                      window.location = "http://bad.website";
                   }
                }
                window.onerror = process;
                process();</script>
        </head>
        <body>
            The Document has moved <a href="http://bad.website">here</a>
        </body>
        </html>

Notably, you can find very similar snippets on Github. The redirect above isn't a new tactic used to redirect users. After this redirect, the user is at the attacker's final destination.

About the attacker's site

I've played around with the attacking site. Fun fact: the redirect page changes depending on your IP/location. The page would redirect me to the fake AV scanner if I were in North America. If I were in Europe, Asia, South America, etc., each would redirect me to different pages showing less-than-desirable content. Is this done intentionally to specialize attack payloads based on some level of effectiveness according to location, or is it just done randomly?

Why this is serious

In general, the attack is widespread, where we can find many compromised websites with a simple Google search of the attacking website's IP address. Many website owners are affected by this, as evinced by this Cloudflare support question. Notably, even this issue found its way to one of the links in the SvelteKit docs.

It is not apparent that the attack impacts WordPress plugins, as @ColinQuarello demonstrated. Newly provisioned accounts are also affected even with no content uploaded to the website. From this, we can assume that this could be a system-wide issue for the hosting provider.

@GoDaddyHelp @GoDaddy 302 redirects are happening from your load balancers to spam/porn sites on the shared hosting infrastructure. I provisioned a new account and immediately got a 302 redirect when there was no content on the site. Headers looked forged too. This is serious.

— Colin Quarello (@ColinQuarello) December 19, 2022

Once a user is in the hands of the attacker by being on the attacker's website, they can succumb to social engineering, phishing, etc. Phishing scams alone cost companies and the general public billions per year.

On the human side, this incident can lead to a loss in user trust not only for GoDaddy but also for small to medium-sized businesses that rely on the platform to host their company's website, e-commerce store, etc. These days, user trust is more important than ever to foster user growth and business expansion. According to a study done by DigiCert, "84% of consumers would switch to a competitor if they lost trust in the enterprise". A single incident, let alone repeated occurrences, will degrade user trust faster than a business can regain it quickly.

Latest Developments

As of 2022-12-20, GoDaddy is currently working on this incident (INC-5492776). I am unsure if this is an internal incident tracking number or something GoDaddy customers can access.

We're aware of the issue and working to correct it now. I can assure you that our teams are diligently working to restore service as soon as possible. ^CG

— GoDaddy Help (@GoDaddyHelp) December 20, 2022

Previously, it was suspected to be a firewall-related issue, but this has since been disproven. GoDaddy engineers and users have found this issue occurring regardless of firewall configurations.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

🚀 Cirrus 0.7.1 Released - New utility classes, Accordion, and more

Stanley Lim — Mon, 31 Oct 2022 19:39:43 +0000

Hey everyone!

Just released 0.7.1 for Cirrus. Check it out! The focus for this update was to add new utility classes for absolutes, transitions, etc, add the new Accordion component, and more.

💎 Cirrus
📝 Documentation

What is Cirrus?

Onto the Updates

🎉 Features

Add configurations for specifying custom font families for primary and secondary fonts. dfaadb1
Removed auto-imports for Google fonts for GDPR compliance. dfaadb1
Add btn--disabled class to support diabled state for div and a tags. 8565138
Button shadows now rely on CSS variables. d9fc6ac
New map added to _config.scss to include fg and bg colors. faac886
Add new modal--visible class to replace shown class to display modal dialogs. 2c3c6d7
Add new flex-basis utility classes. 23925ed b070926
Add new blur filter utility classes with viewport variants disabled. f723636
Add utility classes for fixed widths based on default sizing system. 21e1b5a
Add new utility classes for min/max width using breakpoints. 6a2b469
Add accordion component. 5347b9f
Add border color and border opacity utility classes. ae26f16
Add utility classes for fixed heights based on default sizing system. 7111de8
Add Gzipped build option for Cirrus for Gulp. 8ad2051
Add utility classes for transition durations. d0814bf
Add utility classes for line heights. 6ac14a3
Add 25p, 75p and negative versions of absolute util classes. 4fc644d
Add absolute values for absolute util classes based on default sizing system (limited to 0-4rem). 1e83295 7dfa71f
Add border-width util classes. 374cc0e

🐛 Fixes

Fix bug with non-vertically aligned toggle component for different zoom levels. 368a6db
Move inline image values to constants. 6b5a999
generate-classes-for-viewport should reuse logic from generate-classes-for-viewport-with-map. 37c5f8e
Transparent border added to default style for all elements so border util classes will show up. b6e3a9f
leading-none should have a line height of 1 instead of 0. ee293be

💥 Breaking Changes

Themed button classes now respect changes in control-themes map inside _config.scss. faac886
Updated _config.scss to have components (e.g. avatars, tabs, etc.) as top level attributes in the config instead of having avatar-sizes for example.

Before

...
avatar-sizes: (),
breakpoints: (),
button-sizes: (),
...

After

...
avatars: (
    sizes: ()
),
breakpoints: (
    widths: (),
    breakpoint-pairs: ()
),
buttons: (
    sizes: ()
),
...

Remove ms vendor prefix for flexbox due to high CSS3 standard adoption. 34c838b
Remove prefixes for remaining styles that have > 98% unprefixed adoption according to caniuse. b1d1fb1
Remove all remaining CSS prefixes except -webkit-tap-highlight-color. eff211e
Fixed viewport classes for col where it was shifted 1 level wider than expected in 0.7.0 628a815

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on

Airpods Not Charging on Windows ⚡

Stanley Lim — Tue, 23 Aug 2022 02:50:07 +0000

Airpods are pretty cool, especially when you never have to worry about the tangled mess of wired headphones. What’s not cool is when you own a Windows machine and plugging the USB wire to charge your Airpod doesn’t work. The steps below should apply to all Airpods, but I have personally tested it using a first-generation Airpods Pro. I only realized this was a problem when after leaving the Airpods to charge via my laptop USB port for days, it never seemed to charge.

This guide is for anyone who has tried to charge their Airpods to no avail despite many resets.

What was not the issue

If you look online, most of the guides will suggest you reset your Airpods in case there was some other internal failure, such as the firmware for both Airpods being out of sync. Before you proceed with the rest of this guide, I recommend following those steps here first.

The fix

The root cause of this issue is a driver problem. To fix it, all you have to do is:

Connect your Airpods case with your Windows machine using the charging cable you have.
Open Control Panel and click 'Devices and Printers'.
Under the 'Unspecified' dropdown group, you should see 'AirPod Case'. Double click this item.

Open the 'Hardware' tab and double click 'HID-compliant vendor-defined device'.

Click on 'Change settings'.

Click 'Disable Device'.

Finally, unplug and plug in your AirPod case. At this time, your case should charge correctly.

I hope these steps fixed the issue. If not, feel free to consult other guides or give it a good old slap to get things working again.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

⚡The Fastest Way to Develop and Deploy Your Next Project

Stanley Lim — Thu, 09 Jun 2022 17:47:34 +0000

👋 Hey everyone!

Do you like launching stuff? I like launching stuff! A few months ago, I released one of the largest updates to my CSS framework, Cirrus. Cirrus is a CSS framework designed for rapid prototyping and production use with a wide variety of ready-to-use components to plug into your app and utility classes to customize them. This makes building anything new with Cirrus a breeze with dead simple configuration and little overhead.

Cirrus Start is my next project that pushes Cirrus to the next level. The first step with any project is to read the setup section of the documentation. This involves hours or even days to get things going the way you want them. Sometimes the documentation is bad, confusing, or both. Even with good documentation, who wants to spend all that time learning a whole new framework in-depth to get the ball going?

Introducing ⚡ Cirrus Start, the fastest way to bring your idea to life with a framework designed for rapid prototyping. Out of the box, Cirrus Start comes with:

💎 Direct integration with Cirrus using Sass configuration. This allows you to customize what features you want in Cirrus and which classes to add/remove during project generation.
⚙️ Webpack to bundle all your assets in a fast and configurable manner. This includes a few standard Webpack plugins and a live reload server for fast iteration.
⚗️ PurgeCSS is included by default to minimize build sizes and remove all Cirrus classes that are not used for builds.
⚡ Surge.sh to deploy and tear down your project with ease.

How do you use it?

First clone the repository.

Open the cloned repository in your favorite editor.

Try running the local server.

Make any edits you want to make.

Deploy your site to Surge.sh!

How do I customize Cirrus?

Cirrus is loaded within src/index.scss. The file contents is quite simple.

// Configure 
// https://www.cirrus-ui.com/getting-started/configuration
@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        extend: (
        )
    ),
);

// Other Styles
body {
    background: url('https://raw.githubusercontent.com/Spiderpig86/Cirrus/gh-pages/cirrus-docs-next/static/img/gradient.jpg') no-repeat 50%;
    background-attachment: fixed;
}

I strongly recommend reading more about how to customize Cirrus using the configuration mapping here to configure it the way you want. However, configuration is not necessary and you can use the framework as is!

If you'd like to have Cirrus specific configs placed in a separate file, you could move it to a file like src/cirrus.config.scss. Just remember to add import './cirrus.config.scss' inside index.js.

This pretty much ends my spiel on Cirrus Start. I can't wait to see what all of you will build with this! And of course, feedback will be appreciated. 😊

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

The Browser in the Browser (BITB) Attack: Lies, Deceit, and CSS

Stanley Lim — Wed, 30 Mar 2022 16:33:28 +0000

The attack, possible enhancements to the attack, and any attached source code are to be used for educational purposes only. By no means use them for illegal activities such as phishing. You are responsible for your own actions.

Restating the disclaimer mentioned in mr.d0x's repository: Usage of these templates for attacking targets without prior consent is illegal. It's the end user's responsibility to obey all applicable laws. The developer is not responsible for any misuse of these templates.

“Beware the Ides of March”, they say; and we should for good reason.

On March 15th, a security researcher by the name of mr.d0x published an article a nearly undetectable phishing attack that most users would quickly overlook as a legitimate sign-in dialog. This form of phishing, coined as the Browser in the Browser attack, presents a large complication to the web’s growing reliance on SSO and OAuth dialogs to authorize and authenticate users to online services like social media, cloud storage, and other platforms that may store sensitive user information. Common examples of this we see today are signing into other services with our Google Account, Microsoft Account, etc. which we would automatically trust due to reputation.

This attack takes advantage of the trust users built with these sign-in processes to steal credentials by replicating a fake OAuth modal using plain old HTML, CSS and JS.

Origins

While this attack is making headlines today, it is a variation of something that has existed since the late 2000s. Back around when Windows XP still had over 80% market share and Internet Explorer was the most used browser in the world, fake online antivirus scanners started to pop up at every corner of the internet. Since Windows wasn’t known for its stellar security features, selling fake and harmful malware disguised as antiviruses was a very lucrative business, with 3 companies racking up a total of $130 million during their existence.

The goal of these fake antivirus scanners was to scare users into purchasing their “antivirus” since their machine was magically infected one day. These phishing sites flooded your screens with Windows XP or 7 looking windows consisting of flashing red text, a large list of viruses, and giant call-to-actions coercing you to register the product to save your computer from certain destruction. For Windows XP, you would see something like this.

Eventually, attackers became more sophisticated and started emulating window dialogs from your operating system which made it more believable that this was an official product.

A panicked user would obediently follow the prompts to download the scareware which launches the fake antivirus with a “trial” period. After that period ends, it will degrade the performance of the host machine or flood it with more malware to convince the user to purchase an official license to remove all the adware, spyware, and other crap it put on your machine. Once the victim purchases the software, the attacker now has your name, billing address, and credit card information to perform whatever transaction it wants.

Fake antiviruses are a whole other topic that I can dive deep into, but the part of this whole phishing exercise that is still very effective and is presented in mr.d0x’s blog post is the usage of a fake window inside of a webpage.

The Attack

mr.d0x’s proof of concept is an evolution from what we saw with the fake antivirus scan windows. Instead of displaying a scanning page with system-related details, this proof of concept phishes uses a malicious OAuth dialog akin to signing up for an online service using a third-party account. If this doesn’t sound familiar to you, then the GIF below may be more familiar.

Sample OAuth dialog from Facebook’s JavaScript SDK.

The first portion of this attack requires the victim to visit a compromised domain where the attacker set up the trap. This can either be done using IDN Homographs or DNS poisoning/spoofing. This portion of the attack is probably the harder part to implement and convince users to visit the site for reasons explained below. The most convincing approach is to use DNS poisoning, but that in itself is harder to set up.

Assuming that the attacker successfully lures the victims into the phishing site, by cleverly designing the page to look as legitimate as possible to an existing sign-in page today, the attacker should be able to convince users to sign in via some third party service. Once the user clicks the ‘Sign In’ or ‘Sign Up’ option, they will be presented with a fake popup window that loads the attacker’s fake login page. Once the user enters their credentials, the user has been completely compromised.

The Code

The demo mr.d0x created provides templates for creating fake popup windows for several popular operating systems and their variants. Each folder for each OS has these files:

├───Windows-Chrome-LightMode
│       index.html
│       logo.svg
│       script.js
│       ssl.svg
│       style.css

index.html is just a test page that contains the <iframe>.
logo.svg is the favicon used by the fake window.
script.js contains the logic for dragging the window, animating the buttons, etc.
ssl.svg is the lock icon you would see in the address bar of the popup window.
style.css contains styles used on the page.

The code for the window is quite simple and setup instructions can be found in the README. It should work like what is shown in the GIF below.

A gif from mr.d0x’s BITB repo demonstrating how it works.

Enhancements in the Fork

After seeing the templates provided in the repository, I decided to play around with it to make things more convincing and created a fork here. Currently, the templates are very well designed for each OS which makes it look seamless, however, some interactions with the popup can lead more experienced users to easily tell that this is fake.

Out of curiosity, I wanted to see what other changes we can do to make this more believable. To keep things simple, I mainly focused on enhancing the Windows dark theme in a directory called Windows-Chrome.

I first changed the title and address bars to correspond to a login that existed, such as the Google sign-in page. I then fixed up some of the styling involving the fonts, alignment of text elements, and the overflow of the address bar so the text doesn’t look cut off.

To make the window loading more realistic, I added some random delay when displaying the page and an opacity transition when showing and hiding the window.

The next thing I did was made the window itself resizable. The user should be able to drag the window in all directions just like a real one would. This came with some challenges that were solved with some clever CSS trickery during dragging and not dragging.

The final step was creating a sample phishing page with the SSO sign-in button and creating a modified version of the Google login page that looks similar to what we see today. The only thing I added was a new password field (which is shown when we hit next but that was pretty hard to replicate) and a custom function for when the user hits enter/clicks next. For any seasoned user, they would be able to tell that Google no longer places a password field under the email field in the latest version of the sign-in dialog.

For the phishing page that launches the fake OAuth dialog, we can make things more convincing by setting the href to a real-looking Google sign-in URL and having an onclick function that returns false. By doing so, the browser will ignore the href and run your JavaScript function instead.

<a
    href="https://accounts.google.com/o/oauth2/auth/identifier?response_type=code&client_id=1083004"
    onclick="return loadWindow()"
    class="clickme u-flex text-gray-800 font-normal"
    id="clickme"
>
    <div class="icon">
        <img class="icon-svg" src="https://upload.wikimedia.org/wikipedia/commons/5/53/Google_%22G%22_Logo.svg" />
    </div>
    <p class="btn-text m-0 u-flex u-items-center"><b>Sign in with Google</b></p>
</a>

function loadWindow() {
    setTimeout(() => {
        $('#window').toggleClass('visible');
        $('#content')[0].src = "phish.html";
    }, 100 + Math.floor(Math.random() * 500));
    return false;
}

After these changes, the final result looks like this:

Further Enhancements

What I mentioned prior is not an exhaustive list of enhancements that can be made to the existing phishing template. Some other things that could be added are switching between dark and light themes depending on whether the user has a light-colored or dark-colored operating system. It would still require some refactoring of the existing template to bundle multiple variants of the window there, but it can be done relatively easily.

@media (prefers-color-scheme: dark) {
  /* Dark theme styles go here */
}

@media (prefers-color-scheme: light) {
  /* Light theme styles go here */
}

Another enhancement would be to add window states to simulate when the window is in focus and out of focus.

Why this is effective

This attack wouldn’t be as effective on observant users who are well aware of similar attacks such as this. However, where this phishing attack shines is how it can mimic a legitimate environment so closely that most users wouldn’t think twice about entering their credentials. To the average user, seeing a lock and a trusted domain in the “address bar” is enough verification to trust the login page they are currently seeing.

Browsers won’t be able to effectively tag which popup iframes are malicious and which aren’t making it very difficult to solve. The HTML structure of the page would not be too different from another website that uses iframes and browsers would have to scan for different variations of class names to identify if the page is displaying a fake popup window or not. Therefore from a web browser standup, not much can be done.

One project that aims to tackle this by alerting every iframe (including legitimate content) is odacavo/enhanced-iframe-protection. It’s a good first step towards addressing this issue but proves to be very cumbersome as you would need to allow-list all frames yourself.

Why it is not effective

The major reason why this attack does not work is that it relies on the user landing on a phishing domain, to begin with. Browsers today are baked in with multiple measures to let users know whether a website is a phishing site or not such as:

Displaying phishing warnings for suspected phishing sites.
Highlighting the domain in the address bar.

These measures generally help users to be more cognizant of possible attacks, but not all will pay attention to these warnings.

Assuming that the victim is not aware of the phishing page, the next stage of the attack still has plenty of holes that the user can poke to realize that they are being duped. For starters, some of the possible criticisms addressed with my enhanced fork include:

Missing window behavior such as resizing.
Weird clipping of the address in the address bar on the right side.
Instant load of the window (added fake delays).

Even with the enhancements, there are still lots of holes in the phishing attack. The first glaring issue is figuring out how to handle the window frames of all operating systems in existence? Sure, we can use the Windows and Mac OS window design to fool most users, but even these common operating systems also come with different variants and shades. Designing a bunch of Windows to match all these variations is a huge waste of time. Not to mention all the different combinations that come with different Linux distros. I mean, seeing a Windows border frame on Mac OS is just sloppy and embarrassing.

The second issue is that the fake OAuth dialog window cannot be moved outside the browser. You’ll notice that attempting to drag it outside the browser would just cause it to get stuck at the edge of the page. Minimizing the browser would also hide the window with it. There is no trace of it in your taskbar and it won’t be shown on Task View for Windows or Mission Control on Mac OS.

The third big issue is that if you use a password manager (which you should be using, offline or not), your password manager will not fill out the login information because you’re not on a website your password manager trusts. This should be a very clear indication that something is not right and you should migrate away from the page immediately.

Mitigations

To counter this phishing attack, below are a few things you can do:

Check the popup window and compare it to your OS’s window controls. If it looks different, then you are being phished.
Try moving the fake popup window outside the browser, checking to see if it shows up as a window in your taskbar, maximize, minimize, etc. If it does not work as expected, then it is a phishing attack.
If your password manager does not autofill the details, then you are on a phishing site.
Setup 2FA/MFA on your online services to add extra protection from any compromised credentials.
Install NoScript. An extreme way to mitigate this issue, but it will 100% work.
Spoof your user agent. Any possible user-agent detection by the phishing site to show the correct window won’t work correctly.

Conclusion

The new, or old I should say, browser in the browser (BitB) attack may be making a comeback for the 2020s — this time in the form of fraudulent OAuth popups. Although this method of phishing is extremely convincing to most, modern browsers offer a large amount of protection against phishing sites already which stops users before they even land on the phishing site. A plethora of issues already makes this attack less effective than it could’ve been. Its lethality, however, comes from browsers failing to block the phishing site. The sign-in dialog’s appearance gives most users a false sense of security leading the user to input their credentials.

It’s possible that in the future more of the things we are used to on the web, such as accepting cookies on sites, may also be weaponized against us by attackers.

References

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

🚀 The fastest way to design and implement your app - Cirrus 0.7.0 is now out!

Stanley Lim — Tue, 22 Mar 2022 16:33:27 +0000

👋 Hey everyone!

In the middle of the pandemic, I sought to rewrite Cirrus to fix many of the issues and inconsistencies that plagued its previous versions and launched on November of 2020. It was well received and definitely inspired me to keep on going.

This year, I am releasing a new version of Cirrus that focuses on the framework's future. There are often debates on whether component-centric frameworks such as Bootstrap or atomic-classed frameworks such as Tailwind are better for its:

Learning curve
Maintainability
Flexibility
Ease of use

Cirrus is a framework that takes the best parts of both of these types of frameworks and provides:

Many pre-built basic components to accelerate your development velocity (e.g. Avatars, Modals, Tabs, etc.). To keep your code clean, all component classes are built following the BEM convention.
A suite of common utility classes to help tweak and polish your designs when needed. These utility classes are so powerful that you can construct components with them alone.
Different CDN builds of the framework that can be dropped in at any browser (core, ext, all). Choose one that fits your needs.

With the release of 0.7, much of the framework can now be customized. Since the framework is written entirely in Scss, it can take advantage of all the existing APIs for class generation. The new configuration system in Cirrus allows you to:

Add/Edit/Delete component styles.
Add/Edit/Delete utility classes.
Specify which breakpoints are supported.
Toggle which classes should have viewport variants (to help save on build size).
Enable/Disable different parts of the framework.
And more :)

😵 So what's actually new?

🌞 A new way to use Cirrus

With previous versions, the only ways to use Cirrus was to either linking the CDN link at the top of your page or importing cirrus-ui into your Node project.

This is fine, but it lacked any sort of customization. The only way to change Cirrus was to clone the project and build your own version locally. Dart Sass has given me immense opportunity to improve Cirrus's usability and fix technical debt and hacks. One of the things it also enabled was directly importing Cirrus into your Sass/Scss project directly.

Not only can you import different pre-configured versions of Cirrus, but also take advantage of all the functions, mixins, constants, etc. that Cirrus comes built with.

// main.scss
@use "cirrus-ui/cirrus-core" as *; // Core build OR
@use "cirrus-ui/src/cirrus-ext" as *; // Extended build

@screen-above($md) {
    .my-class {
        background-color: rgba(#{hex-to-rgb(fill('blue', '600'))}, .25);
    }
}

No more having to build Cirrus separately and then copying and pasting the generated styles to your project. Read more on this here.

🔨 Focus on configurability

One of the things this rewrite aimed to accomplish was configurability. In the past, CSS frameworks were just things we plop into our project and we either accepted styles it gave us or we spent countless hours overriding them to fit our needs. Why should we continue to subject ourselves to that amount of torture?

0.7.0 marks a big step in dynamic class generation. Whether you are building Cirrus locally or you're importing Cirrus directly into your Sass files, you can take advantage of defining a configuration object in both scenarios when you import the framework. Use the configuration object to specify viewports for classes, extend existing component and utility styles, toggle features, and more.

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: (
            ABSOLUTES,
        ),
        opacity: null, // Disable default opacity classes
        extend: (
            // Add your own
            opacity: (
                25: .25,
                50: .5,
                75: .75,
            )
        )
    ),
);

Currently most utility classes and components can be customized through here in this release, but I hope to extend this capability a lot more in future updates. Read more on this here.

🎨 Revamped colors

Default colors have been tuned a bit for increased vibrancy and range. Of course, these colors can be customized via the configuration object as well.

Check out all colors here.

⚡ Utils, utils, and more utils

Utility classes within Cirrus have grown to be quite popular. This update adds utility classes for:

Letter Spacing — utilities to control letter spacing of an element.
Flex Wrap — utiltiies to control how flex items wrap.
Flex Grow — utilties to control how flex items grow.
Flex Shrink — utilities to control how flex items shrink.
Color Opacity — utilities to control color opacity (background and text/border).
Flex/Grid Gap — utilities to control gutters between grid and flexbox items.
Font Size — utilities for font sizes.
Box Shadow — utilities to add box shadows to an element.
Border Radius — utilities to control border radius of an element.
Min Height — utilities to set min height of an element.
Max Height — utilities to set max height of an element.
Min Width — utilities to set min width of an element.
Max Width — utilities to set max width of an element.
Font Weights — utiltiies to control font weight of an element.
Opacity — utilities to control the opacity of an element.
Z-Index — utilities to control the z-index of an element.

A lot of classes have also seen the introduction of viewport variants. Those can be found in the class specific documentation in the docs page.

<div class="u-z-50 ...">50</div>
<div class="u-z-40 ...">40</div>
<div class="u-z-30 ...">30</div>
<div class="u-z-20 ...">20</div>
<div class="u-z-10 ...">10</div>
<div class="u-z-1 ...">1</div>
<div class="u-z-0 ...">0</div>
<div class="u-z-n1 ...">-1</div>
<div class="u-z-auto ...">auto</div>

🏗️ Components

This update wasn't as focused on introducing new components, but it was not forgotten. Some of the new components styles are:

Breadcrumbs — a component used to create a sense of hierarchy when navigating a website.
Progress — Cirrus comes with styling right out of the box for the progress HTML element.
New Animations — new animation classes include pulse (skeleton loaders) and ping (notification).

💎 But wait, there's more

Check out all the other changes in the release notes.

😊 Thank You

Before I start blabbering on too much about the technical details, I will end by saying please check out the docs, give it a try on the playground, and let me know your thoughts!

And as always, if you like my work, feel free to follow me on these platforms:

Why I Unit Test My Sass: Mixins 🧪

Stanley Lim — Tue, 01 Feb 2022 17:05:15 +0000

In my previous post, I discussed why Sass unit testing is a thing and why you may want to incorporate it into your project. If you were shocked to find out that this is something that is done, please let me explain in my first post.

Unit testing Sass functions wasn’t too complicated. But what about mixins? Testing-wise, it is quite similar. The only difference here is the syntax.

Getting Started

Note that the steps outlined here assume you have set up your test project similar to how it is described in the first post. If you have an existing project, you can follow along and delete the test artifacts later.

For this tutorial, let’s create a simple viewport mixin similar to the screen-above() mixin defined in Cirrus. The mixin below will apply any styles passed into it if it is larger than the specified breakpoints. Copy the contents below into a new file within /src/mixins.scss.

// mixins.scss

$breakpoints: (
    $xs: 640px,
    $sm: 768px,
    $md: 1024px,
    $lg: 1280px,
    $xl: 1536px,
);

// Applies styles for viewports greater than a certain breakpoint. An error is thrown if the breakpoint does not exist.
@mixin screen-above($breakpoint) {
    @if not map-has-key($map: $breakpoints, $key: $breakpoint) {
        @error 'The given breakpoint #{$breakpoint} for @screen-above does not exist.';
    }

    @media screen and (min-width: map-get($breakpoints, $breakpoint)) {
        @content;
    }
}

Testing

Before you write the test, make sure you have already done the prerequisites required to run Sass unit tests in the first place. You can read all about it in my first post here.

Let’s start by creating our test file for mixins in test/mixins.spec.scss.

@import 'true';
@import '../src/mixins.scss';

Let’s add our test block with the @describe annotation.

@include describe('screen-above()') {

}

Next, we will add our test case.

@include describe('screen-above()') {
    @include it('should return screen-above 640px given $xs') {

    }
}

Then, we will use the assert() mixin to take the actual output and the value we expect. Below we place the .test class in the output that includes the screen-above mixin. The expect would contain the CSS output we expect.

@include it('should return screen-above 640px given $xs') {
    @include assert {
        @include output {
            .test {
                @include screen-above($xs) {
                    color: #fff;
                }
            }
        }
        @include expect {
            @media screen and (min-width: 640px) {
                .test {
                    color: #fff;
                }
            }
        }
    }
}

To summarize this better:

expect - describes the expected results.
output - the actual output from the mixin you are testing.
assert - a clause that binds the output and expect mixins together for the test.

Running Your Tests

Like in the previous blog post, you can now run npm test to execute Jest for us. To be honest, it’s probably faster to just type jest instead.

npm test

You should see the results of your first test similar to the output below:

 PASS  tests/scss.spec.js
  Sass
    screen-above()
      √ should return screen-above 640px given $xs (1 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.143 s, estimated 4 s
Ran all test suites.

Conclusion

Well, that wraps up the tutorial on how to unit test mixins in Sass. In the next post, I will discuss how we can add error handling within our Sass that can be caught and tested using True.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.

Why I Unit Test My Sass: Functions 🧪

Stanley Lim — Mon, 10 Jan 2022 16:30:39 +0000

Did you know you could unit test your Sass/Scss? No? Me neither.

If you were to ask me years ago if there was such thing as unit testing Sass let alone stylesheets, I would tell you that it would probably be manual or automated with some framework like Selenium. Testing would be slow, arduous, and not very lightweight.

This was the past and luckily, we now live during a time where we have choices.

Today, there exists a nifty little testing framework called True that allows you to quickly write Sass unit tests without too much pain. It features a syntax that makes most front-end developers feel at home. If you have ever written unit tests using Jest, then using True won’t actually be that much different.

Why Unit Test Sass?

Before we dive into the tooling, let’s discuss why we should do it in the first place.

As a basic example, let’s say you’re building a simple application that takes employees' orders for Pizza Friday. It’s a simple form that people in your team can select some radio box for which pizzas they want. You manually test, ship, and it becomes a big hit within the company.

Now the people demand more features. Next, they ask you for dropdowns to allow for customization. You rinse and repeat the process above and you ship it. Now suddenly, people aren't too fond of radio boxes because it doesn’t allow them to select multiple types of pizzas. You go back and make some changes and test. Fearing that you may have broken other parts of the app, you manually test as well. Each successive update becomes more and more of a drag until you decide to give up maintaining it all together.

The point is, unit testing solves the repetitive and arduous task of manually testing features over and over again. It is essentially:

A built-in sanity check for any new feature/integration into your existing application.
A record/collection of all possible cases that may break your app. It is essentially free documentation for app behaviors given some input.
Ensures that the code is maintainable even if someone else works in your codebase and makes a breaking change. Unit tests, if written properly, will catch those.
Fewer fires in prod. No one likes putting out fires on a Friday night.

These principles apply to so many parts of software development, so maybe it wouldn’t be too farfetched to also unit test your Sass. If you have a large project with lots of generated styles, debugging issues won’t always be that straightforward. Unit testing Sass should help with:

Asserting that the inputs to your functions and mixins output what you expect.
- This is especially important if you use any third-party libraries. You don’t want your stylesheets breaking because of some breaking change upstream.
Reduce the amount of manual testing required for checking styles.
Checking Sass compilation errors that generate some of your stylesheets properly.

Is this for me?

I usually advocate for more testing regardless of the size of your project, but it might not be appropriate for what you are building. You should be testing if:

You use functions and mixins in your project, especially if they are on the more complicated side.
Your Sass files are used in many other files.
Your customer experience highly depends on how reliable the UI is rendered correctly. For example with an e-commerce site, you wouldn’t want your styles to accidentally hide the “Buy” button with some adjacent element.
You’re building a library, like Cirrus.

Caveats

Although unit testing Sass sounds like it will solve all your design problems, it doesn’t. Using a framework like Sass True would help to make sure that the CSS generated is what you expect, however it is only limited to testing functions and mixins.

The final CSS output is really up to you to double-check and verify by hand. The same applies to whether the Sass would compile properly or not.

So how do I get started?

The tutorial below walks you through setting up unit testing for a random Sass project. If you have another project you would like to add this to, then it may require some modification to the steps to fit your needs. We will be using Dart Sass as our transpiler of choice and the Sass True framework backed by Jest to write and perform our tests.

In your project, first install the necessary dependencies:

yarn add dart-sass sass-true glob jest

Initialize your node project.

npm init

In your package.json, define a test script to trigger Jest.

"scripts": {
    "test": "jest"
}

To test, the first thing we need to have is source code. If you don’t have any, you can copy this string-split function to use an example and add it to src/functions.scss.

/* functions.scss */
@function string-split($string, $delimiter) {
    $result: ();

    $index: string.index($string, $delimiter);
    @while $index != null {
        $substring: string.slice($string, 1, $index - 1);
        $result: append($result, $substring);
        $string: string.slice($string, $index + string.length($delimiter));
        $index: string.index($string, $delimiter);
    }

    $result: append($result, $string);
    @return $result;
}

For this tutorial, we want to write unit tests to ensure that our string split function works as expected.

Bind Sass True with Jest

With that part done, let’s integrate Jest to work with Sass True. In essence, Sass True acts as the glue or Shim that binds your unit tests written in Sass into something that Jest can interpret.

For our tests, let’s create a test directory. Here we can throw whatever unit tests we want along with our shim file. Copy the shim file contents below and paste it into test/scss.spec.js.

// scss.spec.js
const path = require('path');
const sassTrue = require('sass-true');
const glob = require('glob');

const testPath = `tests/**/*.spec.scss`;

describe('Sass', () => {
    const testFiles = glob.sync(path.resolve(process.cwd(), testPath));

    // Run on each file with describe() and it() functions
    testFiles.forEach((file) => sassTrue.runSass({ file: file }, { describe, it }));
});

What this shim file does is search for all files ending with the .spec.scss extension to be unit tested. We use glob to resolve all paths given the testPath regex.

For each test file, we will use Sass True to run the tests defined. In the second parameter of runSass, we pass in the functions that we would want to use such as describe and it within our Sass unit tests. If you are not sure what these functions do, luckily you can refer to the Jest Documentation because they behave exactly the same as their JavaScript counterparts.

Writing Unit Tests

Now comes the fun/boring part. Now we have to write the actual tests for our string-split() function. Let’s create our first test file under the path test/functions.spec.scss.

The first thing we need to do is import the Sass True library and the file we want to test itself.

/* functions.spec.scss */
@use 'true';
@use '../src/functions.scss';

What comes after will look very familiar if you are used to unit testing with Jest. The syntax is almost identical to writing JS, except = with a few minor syntactical differences. Instead of function calls, each of Jests’s global functions is defined as a mixin. First, let’s describe the item we are testing. This helps to group multiple test cases that test the same thing together.

@include describe('string-split()') {

}

Next, we will define the test cases themselves. We use the it aka the test keyword to specify each input we want to test our function with.

@include describe('string-split()') {
    @include it('should return input string split using delimiter ","') {

    }
}

To wrap this test case, we need a way to check whether the output value is what we expect, commonly known as asserting our output. The assert-equal($assert, $expected) mixin is perfect for checking the output of string-split(). The first parameter is what’s output by the function under test and the second parameter is the expected output of that value. You can read more about it here.

Let’s say we want to test our function with an input string of apples,oranges,bananas with a delimiter of ,. Then, we should expect our output to be (‘apples’ ‘oranges’ ‘bananas’). We can write our test like this:

@include describe('string-split()') {
    @include it('should return input string split using delimiter ","') {
        @include assert-equal(string-split('apples,bananas,oranges', ','), ('apples' 'oranges' 'bananas'));
    }
}

Now you are ready to run your first test.

Running Your Tests

Remember that script we added in the package.json file earlier? We can now run npm test to execute Jest for us. To be honest, it’s probably faster to just type jest instead.

npm test

You should see the results of your first test similar to the output below:

 PASS  tests/scss.spec.js
  Sass
    string-split()
      √ should return input string split using delimiter "," (1 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        1.058 s, estimated 6 s
Ran all test suites.

🎉 You did it 🎉

Well, congratulations! Give yourself a big pat on the back for writing your first unit test in Sass.

Unit testing is the most glamorous topic in any aspect of software development. It is arguably the part that developers dread the most as it is repetitive, boring, and disappointing when you find out the code you wrote is broken. However, it is the most essential mechanism that keeps code maintainable and explicit. Edge cases are explicit and all it takes is a single command execution to confirm any assumptions you had on how the system behaved given certain inputs.

I previously thought Sass unit testing would never be a thing and why would it be a thing that developers would try to figure out. Today, I cannot think of developing Cirrus or any large projects with hundreds of styles without unit testing.

Anyway, don’t forget to check out True’s amazing documentation to learn more about what else it can do. In the next post in this series, I will go over how you can easily test your mixins.

Thanks for reading!

💎 Thank you for taking the time to check out this post. For more content like this, head over to my actual blog. Feel free to reach out to me on LinkedIn and follow me on Github.