DEV Community: Evgeny Khoroshilov

Beyond procrastination: the cognitive reasons behind unfinished projects

Evgeny Khoroshilov — Mon, 23 Dec 2024 13:41:00 +0000

From impostor syndrome to cognitive overload — mastering the invisible forces that prevent project success

Introduction

Remember this sensation: in your mind, a new brilliant project idea sparks, you're burning with excitement and 200% engaged into work, until… another project/framework/technology beckons. And I totally get it - it's always greener on the other side. Notebooks are filled with half-finished concepts, Github repos multiply with ambitious beginnings that won't ever reach their final stage. What starts as passionate creativity often transforms into a stockpile of unfinished potential, an accumulation of partially constructed projects. Sounds familiar, doesn't it? Well, it's not just you. In fact, it's quite common.

Our relationship with incomplete work is far more nuanced than simple procrastination. It's a complex relationship of creativity, neurological reward systems, and the profound psychology of potential. When we understand how it works, we can transform seemingly scattered efforts into a powerful attribute of self-improvement.

Look at this from a different angle: those aren't graveyards of failed projects, but the living laboratories. Each unfinished activity represents a moment of intellectual curiosity frozen in time. Curious? Great! Let's dive into the complex psychological and neurological mechanisms driving technological exploration.

Short track:

Jump right to this chapter - “Strategies for Meaningful Project Development“.

The Neurological Roots of Project Incompletion

To try and reveal the roots of the new-projects-problem, we'll explore some ideas, backed up by psychological and neuroscientific works.

Dopamine-Driven Novelty Seeking: The Neural Reward Circuitry

Our brain is evolutionarily wired to seek novelty as a survival mechanism. Dr. Andrew Huberman explains in his neuroscience study that this novelty-seeking behavior stems from our brain's dopamine reward system, which creates a powerful neurochemical response to new experiences.

Dopamine is a neurotransmitter. It is involved in many brain functions and well-known for its role in movement, motivation, and addiction.

Each new technological discovery triggers a dopamine release, creating a neurochemical reward that far exceeds the more mundane satisfaction of completing existing work. Our neural circuits are designed to anticipate and seek out potential rewards, constantly pushing us towards new and exciting possibilities.

Naturally chasing neural circuits satisfaction, we tend to:

alternate projects/technologies/frameworks/etc, driven by the brain's reward prediction mechanism
pursue bleeding-edge and freshly emerging libraries and languages
start greenfield projects instead of maintaining existing repos
immediately hop on to the new technique after a workshop/conference/article

This naturally applies beyond the hobby or side projects. Remember when half-way through refactoring of some legacy codebase you discover a new tech that supposedly speeds up your work and potentially grants your project 50% performance kick?

In his book, "Incognito: The Secret Lives of the Brain", Dr. David Eagleman describes a neural plasticity effect of activation of our brain's novelty circuits. From developer's perspective the new technology seems then more exciting and potentially more valuable than the current mundane work.

Complexity Overwhelm and Cognitive Load

While novelty seeking tends to propagate positive experiences, their amount can become a challenge. Especially when work is paralleled and/or task-switching engaged. Our brain has limited working memory capacity, a concept extensively explored quite a while ago by John Sweller in his Cognitive Load Theory. Relatively recent famous work by Dr. Daniel Kahneman - "Thinking, Fast and Slow" - further elaborates on how our cognitive resources become depleted when faced with complex problem-solving tasks.

For developers, this can be simply demonstrated as a progressive mental exhaustion. The brain's working memory acts like a small workspace that becomes quickly overwhelmed by intricate technical challenges. As project complexity increases, cognitive load creates a psychological defense mechanism of avoidance and task-switching. And, unfortunately, we've often been there:

initial excitement is replaced with cognitive exhaustion
some complex architectural decisions become paralyzing
technical debt creates increasing mental friction
project scope tends to become overestimated

The prefrontal cortex, responsible for executive function, becomes progressively taxed. Stress and complexity directly impact our brain's ability to maintain focus and execute complex tasks. While some of these statements look obvious, there are probably even more deeply rooted brain mechanisms worth exploring. We'll touch them in the next section.

Fear-Based Project Avoidance and Psychological Barriers

Fear is a primal emotion that shapes our most intimate professional decisions. Applied to our realm, fear transforms from a basic survival mechanism into a psychological barrier that can paralyze even the most talented developers. Here are just a couple of the most common patterns that we can experience.

Perfectionism Paralysis

Dr. Pauline Rose Clance's groundbreaking research on the Impostor Phenomenon provides insight into this challenge. The fear of imperfect implementation stems from a deep-seated psychological mechanism where developers:

doubt their technical capabilities
engage in constant reevaluation or refactoring without meaningful progress
compare potential output to an idealized mental model

Impostor Syndrome

Going further with the impostor syndrome, Mike Cannon-Brookes, in his influential TED Talk, describes it as a universal experience among high-achieving professionals. Often met between writers, artists, various creators, and of course developers this results in:

persistent doubt about technical abilities
fear of external judgment and following blockers
preventing project completion to avoid potential criticism

Technology Obsolescence Anxiety

Dr. Cal Newport's work on deep work and technological anxiety suggests that this fear is rooted in our rapidly changing technological landscape. Cobol, Perl and to the very recent time React.js developers are probably on the safe side in this regard. Nevertheless, jokes (?) aside, some of you can remember:

constant worry about implementation becoming outdated
perpetual desire to incorporate latest best practices
endless loop of "one more optimization"

The Incompleteness Addiction

The quagmire of perpetual technological improvements goes arm-in-arm with another concept, hinted on previously. Unfinished projects represent infinite potential. Completion on the other hand means confronting actual versus imagined capabilities, which can be psychologically threatening.

James Clear touches that aspect of human behaviour in the popular book "Atomic Habits". He explores how our brains are wired to find comfort in potential rather than finality. This mechanism protects the developer's self-image by maintaining the project in a state of perpetual promise, avoiding the potential disappointment of real-world constraints and limitations.

If you find yourself in the place of endless proof-of-concept development or... exploring theories over practical implementations or... initializing multiple project versions without finalization you definitely know what's this is about. These neurological and psychological mechanisms aren't weaknesses but sophisticated cognitive strategies.

And you know what else? You are not alone struggling with fear of accomplishment, collecting numerous incomplete projects or hopping styles, genres and technologies. You are, in fact, in a legendary company.

Great Minds and Unfinished Symphonies

Consider Leonardo da Vinci, whose notebooks were living documents of boundless intellectual exploration. He is known primarily as painter; but as a draughtsman, engineer, scientist, theorist, sculptor, and architect he recorded 13000 pages of studies. Needless to say, majority of those works was unfinished. His approach reveals a critical insight: transformative developers are not those who persistently complete every project, but those who remain curious and adaptable.

Franz Kafka was the writer and an existential experimenter. Kafka didn't write stories - he conducted psychological experiments. His fragmented manuscripts weren't incomplete — they were deliberate explorations of human uncertainty. The "Dante" and one of the greatest writers of the 20th century finished none of his full-length novels and burned around 90 percent of his work, leaving his dear friend Max Brod thousands of drafts after his death...

If you aren't familiar with Sir Alfred Hitchcock - the film director and the technological innovator, you would certainly recognize his movie by the iconic scene.

For Hitchcock, each film was an experimental ground. He didn't just create movies; he continuously reimagined the language and shape of modern cinema as we know it. And this next quote is particularly curious, I'm sure it resonates in some of you:

"Once the screenplay is finished, I'd just as soon not make the film at all. All the fun is over. <...> When you finish the script, the film is perfect. But in shooting it you lose perhaps 40 per cent of your original conception."

For Frida Kahlo, the personal technologist, art was a constant negotiation between personal narrative and technical exploration. She is famous for autobiographical paintings, where each painting was a technological and emotional experiment. Kahlo's work has been celebrated internationally as emblematic of Mexican national and Indigenous traditions and by feminists for what is seen as its uncompromising depiction of the female experience and form.

In every creative domain, in every country there are famous figures, known for their works and, incidentally, working methodology. We only met a fracture of a percent of them in this article and I invite you to study more for the unbelievable insights.

While dopamine-driven novelty seeking and cognitive challenges are not obstacles, but intricate neural mechanisms that have driven human innovation, what if they really pose a problem of self-rumination cycles and blocking you from progression to the next level? We'll now explore several critical strategies that can help you to channel your creative energy into meaningful outcomes.

Strategies for Meaningful Project Development

Progressive Rendering

Inspired by artistic techniques and incorporated in JPEG technology, progressive rendering is a methodological approach to project development that prioritizes incremental progress over perfection from the get go.

Consider the two practical phases - sketch and layering.

In the sketch phase you create the most viable version of the project, focusing on the core functionality and basic structure. You simply don't need anything else beyond fundamental architecture and primary usability. If it's a UI library, forget rounding and line height alignment - focus on API, build process and delivery. If it's a landing page, don't mind the parallax effect and concentrate your efforts on the scalable accessible mobile-first layout.

In the layering phase you progressively (layer by layer, iteration by iteration) add complexity and refinement, implementing features in order of priority and impact. At the end of each iteration you need to validate it against the final project vision to understand the scope of the next layer. This stage is crucial, as taking a larger scope into the next iteration (adding several features or underestimated chunk of work) can result in unexpected blockers following by scattered effort, losing focus, momentum, flow and satisfaction from the previously completed steps.

The benefits of this technique are tremendous:

it reduces cognitive overload
it provides early validation of the core concept
it creates tangible progress that motivates toward further development
it allows for flexible adaptation as project understanding hardens

I foresee the silent question - "did you just reinvent Scrum?! interrobang, interrobang".

Well, fair enough, it's one of the key aspects. However, in practice working by Scrum doesn't always mean actually understanding it. Let alone personal projects management when you are working alone constantly changing hats of angel ventures, stakeholders, product owners, scrum masters AND developers. But if you master or at least exercise that, your personal workflow improvements will be mirrored and rewarded as you grow professionally.

Intentional Pruning

Continuing with the efficient practices for project management, intentional pruning is a disciplined approach that involves deliberately limiting project scope to ensure meaningful completion. In simple terms...

Cut down everything enticing and shiny in favor of functional and achievable!

In order to apply this practice, stick to the following:

evaluate features based on the core objectives
prioritize functionalities with the highest user value
ruthlessly eliminate nice-to-have-s

The latter is probably the hardest, at least from a personal experience…

However, once you push through this once or twice (practice makes perfect!), you'll see immense benefit. Not only you will be able to finish current projects, but your planning and architecture skills will be honed again and again, creating a great working habit. Eventually, feature elimination will be recognized as strategic optimization, not failure.

Sometimes you need to let go to see the wood for the trees.

Graceful Project Closure

Like not every story ends happily ever after, not every project is meant to reach full completion, and acknowledging this is a mark of personal and professional maturity. This is essentially letting go on a BIGGER scale.

To employ this practice you should most probably find yourself in a place of supporting multiple projects in parallel and finding hard time to either complete them or switch to the new ones.

Tempered by the feature-culling experience you should be prepared to take the next steps:

be honest with yourself, and conduct an objective project assessment
identify and extract the learning opportunities from unfinished work
document findings and salvage resources for the future applications

In order to drop the guilt and transform disappointment intro strategic insight, you will need to separate personal worth from project outcomes and view unfinished work as learning experience. Each proper project closure will be identified as another instrument in a toolbox of a professional, who values exploration and iteration.

In Conclusion

Having multiple unfinished projects is way more nuanced than simple procrastination. It often seems as a professional shortcoming and understandably is self-joked upon. But as we've explored together this is both personal challenge and a fundamental aspect of human creative cognition.

This sometimes poses a real issue for developers and creative minds, leading to professional stagnation, reduced productivity and personal frustration. However, by understanding the underlying psychological and neurological mechanisms, we can transform this pattern from a potential limitation into a strategic instrument of self development.

Engage careful analysis, self-awareness and several targeted techniques, and it will help you to channel your creative impulses more effectively, balancing with meaningful execution. The goal is not about a perfect completion, but meaningful progress. Stay curious and systematic and you will succeed!

Thank you for reading!

If you find article useful please support by share and like. This significantly helps with the new articles.

Stay tuned for more!

Behind Fuji X Studio: Lessons in Web development, AI, Design and Accessibility

Evgeny Khoroshilov — Mon, 25 Nov 2024 13:42:00 +0000

Disclaimer 1: This article was supposed to be a book, but ChatGPT quota is against it. If you didn’t get the joke, it’s probably the API latency.

Disclaimer 2: Johan Guterman has fully reviewed, edited and approved this piece. Any copyright breach claims are preposterous, but will be tolerated.

Our application development journey started with a bit of a lazy for Johan and my growing fascination for automation. We both started using Fuji X cameras around the same time and very shortly after were fully charmed by the magic of JPEG film simulation recipes.

“Film Simulation modes are part of what make X Series cameras so special” fujifilm-x.com

Over time, our enthusiasm grew, and we found ourselves wanting something more tailored. Say, I watch some series or a movie and I enjoy the picture so much that I would like to take my photos with that same color effect that I see on the screen. More importantly, I want to get the result before post-production in the dedicated software.

Replicating the cinematic quality of film or digital post-processing in a JPEG recipe is an ambitious challenge, often requiring extensive effort. It requires certain experience, and for beginners it’s a lot of work even in the specialized apps like Capture One or Lightroom (although it gets easier each year with the new or improved tooling).

Despite the challenge, we can (and will) give it a try.

Sure, the results won’t be exactly the same, but:

we can get a unique JPEG recipe named after the series or a movie
it is time we put up AI to the challenge
we can always tune the JPEG-s in the post-processing with a preset

Don’t Blink

“It’s quite simple, really” — Johan explains — “I get to the website, upload some pictures, set my camera features, wait couple of seconds and BAM — get a JPEG recipe similar to Fuji X Weekly

💭 Hm, so we need a form, collection of cameras parameters and some basic communication with AI.

“That it?” — I ask.

“Well, It’d be also great to share the link with other photo enthusiasts! So when they get to the page…”

“Yup, let’s pause here for a second!”

💭 We’ll also need a database to store and fetch recipe params and an image storage, apparently.

“Okay, certainly doable. You were saying?”

“Right, so other people could remix existing recipes!”

“Remix? How does that work?”

“You just click a button…”

“…a-ha and it just works, sure”

💭 Raising AI model temperature and tweaking some other params with the same input data should work.

“Aa-and a nice landing page, of course!”

“Naturally”

“In the Fuji-retro-style, with grids and splashy gradients…”

“We’ll see”

“Oh, and I can write testimonials!”

“Yep… wait, is this all about promoting your Instagram?!”

“Alter… komm schon”

The Implementation — Snap-Snap

Hey there,ChatGPT

To kick off, let’s prototype using a tool we already have at our disposal: ChatGPT.

The very first attempt was to find out the feasibility of the whole affair. To my genuine pleasure, it worked just fine! ChatGPT understood the requirements, correctly processed the images and output a decent starting point for the JPEG recipe… after several back-and-forth-s.

Let’s visualize this:

If we dig a bit deeper and extrapolate this to the application UX the process is not exactly that smooth. In our app we’ll be making a single request and getting a single response.

What we’re looking forward to is something like this:

To get the better idea, just compare a casual conversation (fast response, short messages, information builds on top of the previous data) to an old-school physical letter (slow delivery, long sentences, all details covered to a single detail in one message).

Let’s get to it!

Hello, Open AI API

We reached the important point of designing the request.

Since this is a huge topic on its own, I would only mention a few crucial details.

We evolved from the ChatGPT dialogue to using Open AI API.
API request for the needs of Fuji X Studio is composed of text and image data. Images are passed in the base64 format, which is rather standard.
Text, however is a combination of several information bits. Remember, it’s a snail-mail-physical letter that should not fail. And when it does, failure should be predictable.

Text (aka instructions) consists of:

introduction and the point of request
camera details from the form data, composed in a certain way
JPEG recipe templates for different generations of camera sensors
templates for the output for every parameter
response template
error response templates
instructions for images edge cases

It’s not an exaggeration to note that the AI instructions is the most edited file in the project. Fine-tuning of the text part for request took somewhat the same time as for creating the whole UI for the app.

The full instruction takes around 200 lines and about 7000 characters, resulting in roughly 1800 tokens for every request. Adding images tokens (I admit, we should’ve started with images) to that number will give us around 3000–4000 tokens per request on average. Output tokens volume is somewhat negligible, we limit it to around 250 per recipe.

“Is that much?” — Johan chimes in to check the results.

“Well, it depends. For personal occasional usage it’s pretty much affordable, but for our free app we don’t want to get a hefty tokens bill out of a sudden”

“How hefty?”

“Any unpredictable credit is a risk, especially for a public app”

“We can add a «buy me a coffee» button…”

“Or we can try recently released Gemini AI, it does have vision capabilities and it’s got a free tier. The only catch that it’s not available in EU yet”

“So, about that coffee button…”

“Although, access from EU is not an issue with the cloud functions. But we’ll need another round of testing.”

“I guess I’ll go take some photos then. And a coffee maybe.”

Pivot #1

Looking for alternative to Open AI’s token costs and release of Gemini AI aligned perfectly and resulted in the first turning point in development. In retrospect we can compare not only the price but also the output quality, which may be especially handy for other photo/development enthusiasts.

So how and what are we actually comparing?

Same conditions as before, text request is around 1800 tokens plus two high-res images on average interaction. However for different operators images cost varies.

🤖 Open AI

model: gpt-4-vision-preview (currently several cheaper models are available, i.e. gpt-4o)
image tokens calculation: “A 2048 x 4096 image in detail: high mode costs 1105 tokens”
tokens per user session: (1800 + 2 images x 1100) x 3 retries = 12000 tokens
tokens cost: $10/1M tokens ($2.5/1M for modern models)
user session cost: $0.12 💰 ($0.03 for modern models)

🤖 Gemini AI

model: gemini-pro-vision, later gemini-1.5-flash
image tokens calculation: “During processing, the Gemini API considers images to be a fixed size, so they consume a fixed number of tokens (currently 258 tokens), regardless of their display or file size.”
tokens per user session: (1800 + 2 images x 258) x 3 retries = 6900
free tokens — 1M tokens per minute and 1500 requests per day
tokens cost: $0.075/1M tokens
user session cost: free, then $0.0005 💰

And what about the output quality?

Open AI (gpt-4-vision-preview) seems to be having more proficiency in vision capabilities and in the photo specific area and produces more intricate and detailed output.
Gemini AI (gemini-1.5-flash) is more on the conservative side. It takes more effort, instructions and templates with examples to prompt out the desired effect. But it’s almost 60x times (yes, 6000%) cheaper!

It’s also worth mentioning that upgrading from gemini-pro-vision to gemini-1.5-flash resulted in around 50% cut on response latency. Great improvement!

So, you see, it’s tricky. On one hand, you pay for better output result, spending fewer tokens. On the other hand, spending twice as much tokens and prompt development time for instructions, but it will be nearly free (depending on the volume of course). For personal usage I would still use Open AI for the same or comparable task.

Finally, let’s briefly compare the JS clients and developer experience

The following snippets contain simplified excerpts of actual app code. Note that imageData is identical for both APIs to accommodate a convenient switch from one to another:

type ImageDataPart = {
 url: string;
 type: string;
};

type ImageData = ImageDataPart[];

const imageData = [
 { url: '<base64 data>', type: '<image type>' }
]

Open AI

To work with the API you need an API ke y and have opena i installed.

import OpenAI from 'openai';
import { ChatCompletionContentPartImage } from 'openai/resources/index.mjs';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const imageMessages: ChatCompletionContentPartImage[] = imageData.map(
    ({ url }) => ({
      type: 'image_url',
      image_url: { url, detail: 'high' },
    }),
  );

async function main() {
  let result;

  try {
    result = await openai.chat.completions.create({
      model: 'gpt-4-vision-preview',
      messages: [
        {
          role: 'system',
          content: 'Generate a JPEG film simulation recipe ...',
        },
        {
          role: 'user',
          content: [...imageMessages],
        },
      ],
      temperature: 0.05,
      max_tokens: 256,
      frequency_penalty: 0,
      presence_penalty: 0,
    });
  } catch (e) {
    throw new Error('Recipe cannot be generated, service error');
  }

  return result?.choices[0].message.content;
}

main();

Gemini AI

Similarly, get the API ke y and install @google/generative-a i module to start working.

import {
  GoogleGenerativeAI,
  InlineDataPart,
  Content,
} from '@google/generative-ai';

const genAi = new GoogleGenerativeAI(process.env.GEMINI_API_KEY as string);
const model = genAi.getGenerativeModel({ model: 'gemini-1.5-flash' });

const imageMessages: InlineDataPart[] = imageData.map(({ url, type }) => ({
  inlineData: {
    mimeType: type,
    data: url.split(',')[1], // only the base64-encoded image data
  },
}));

let result;

async function main() {
  try {
    result = await model.generateContent({
      contents: [
        {
          role: 'user',
          // it is recommended by Gemini docs to place image data 
          // before text when it's one image
          // make sure to adjust the code accordingly for you needs
          parts: [...imageMessages, { text: 'Generate a JPEG film simulation recipe ...' }],
        },
      ],
      generationConfig: {
        temperature: 0.65,
        topK: 32,
        topP: 1,
        maxOutputTokens: 256, // correct, output is super humble
      },
    });
  } catch (e) {
    throw new Error('Recipe cannot be generated, service error');
  }

  return result?.response.text(),
}

main();

Strictly speaking, there are no significant differences in the clients. All nuances can be figured out in the docs or/and Github issues. Subjectively, Open AI documentation seems to be more comprehensive and practically better organized. On the other hand, Gemini AI docs are regularly updated and have significantly improved compared to the rather humble release stage.

In addition, it’s worth mentioning one important aspect, such as moderation. When dealing with user images, especially the ones that are meant to be public, especially when the service is paid, it’s crucial to setup a safety net. Both Open AI and Gemini AI have dedicated capabilities. They have a slightly different approach to the setup, but conceptually are quite similar. Explore the docs to learn more.

The Implementation — Development

It’s Alive!

Following a 180 turnround with the AI model and meticulous fine-tuning of instructions we are able to get some consistent recipe outputs. At this point our app looks like this:

The next step was implementing services to save and share recipes effectively. Practically speaking, we need a simple yet efficient database and an image storage.

The backbone of our app is built on Next.js. To manage the database we chose Vercel KV, a Redis-based solution that fits our needs just great. The implementation is not so different from the docs, but just for posterity, let’s have a look at writing and retrieving saved data.

When we get a proper result from AI, we need to save it, along with the form- and meta-data. Later when we retrieve the recipe all we need is an ID. Note that every generation produces a unique ID, hence a new, unique recipe.

To write (save) the data:

import { kv } from '@vercel/kv';

import { getId } from '@/utils/getId';

// unique ID is generated
const id = getId();

try {
  await kv.hset(id, {
    camera: '<camera settings>',
    proc: '<sensor settings>',
    film: '<film settings>',
    light: '<light settings>',
    recipe: '<recipe data as returned by AI>',
    timestampMs: '<latency, ms>',
  });
} catch (e) {
  if (e instanceof Error) {
    let message = e.message;

    return new Response(message, { status: 500 });
  }
}

To read the recipe data we need to know it’s id.

We can get it from params and generate 404 when it’s not located:

import { notFound } from 'next/navigation';
import { kv } from '@vercel/kv';

const Page = async ({ params }) => {
  const { id } = params;
  const recipeData = await kv.hgetall(id);

  if (!recipeData) {
    notFound();
  }

  // return <RecipePage data={recipeData} />
}

export default Page;

And it’s done!

Let’s take care of the images in the next step.

Pivot #2

Vercel Blob was the very first service that we utilized, and it lasted around 2 days of not that really intense testing. And of course it’s not the question of reliability or anything else. We simply getting back again at the question of pricing.

At first glance, the 250MB quota seemed sufficient, right?

Not sure about you, but spoiled by other services pricing I was convinced it’s the limit per day. So when during testing responses started err on the server without any special premise, I discovered the huge red glaring issue in my Vercel storage. It said that the MONTHLY limit was exhausted already.

Going with a plan B. After some quick research AWS S3 emerged as the ideal alternative, despite its more involved setup process, including account and project setting. And if that’s not enough fun, you’ll also get a change to know the one and only AWS SDK. Who needs SST anyway…

You never asked, but I don’t want to be left alone with this.

Here’s how we can upload the images using @aws-sdk (extra code skipped for brevity). The crucial piece is the id, which we figured out previously:

import { S3Client, S3ClientConfigType, PutObjectCommand } from '@aws-sdk/client-s3';

// proprietary util
import { stringToBlob } from '@/utils/stringToBlob';

const s3Config: S3ClientConfigType = {
  region: S3_REGION,
  credentials: {
    accessKeyId: process.env.AWS_API_KEY as string,
    secretAccessKey: process.env.AWS_API_SECRET as string,
  },
};

const s3Client = new S3Client(s3Config);

const blobPromises = imageData.map(async ({ url }, idx) => {
  const pathname = `${id}/${idx}`;
  const [blob, contentType] = stringToBlob(url);

  const putObject = new PutObjectCommand({
    Bucket: process.env.AWS_S3_BUCKET,
    Key: pathname,
    Body: blob,
    ContentType: contentType,
  });

  return await s3Client.send(putObject);
});

await Promise.all(blobPromises);

Similarly, to retrieve the uploaded images we only need the id:

import { S3Client, S3ClientConfigType, ListObjectsV2Command } from '@aws-sdk/client-s3';

const s3Config: S3ClientConfigType = {
  region: S3_REGION,
  credentials: {
    accessKeyId: process.env.AWS_API_KEY as string,
    secretAccessKey: process.env.AWS_API_SECRET as string,
  },
};

const s3Client = new S3Client(s3Config);

const listObjects = new ListObjectsV2Command({
  Bucket: S3_BUCKET,
  Prefix: `${id}/`,
  MaxKeys: 5, // Fuji X Studio images limit
});

const { Contents } = await s3Client.send(listObjects);

if (Contents?.length) {
  imageUrls = Contents.filter(({ Size }) => !!Size).map(
    ({ Key }) => `https://${S3_BUCKET}.s3.${S3_REGION}.amazonaws.com/${Key}`
  );
}

Now our app starts to get closer to it’s final state:

In the end, how does S3 compare to Blob?

For our use case, the extended testing time alone made AWS S3 at least 60 times more effective. And we are still counting.

“So after two 180 pivots, does it mean we get back to the starting point?”

“Only if you haven’t watched «Rick and Morty»"

“Yeah, I don’t really watch cartoons”

“Believe me, you do in a parallel universe, Johan”

The Implementation — Post Processing

At this point, the app is functioning, but somewhat not complete. Let’s have a brief look on couple of other nice-to-have features.

Kill-Switch

A simple kill-switch mechanism is needed to temporarily disable the service while leaving essential pages and metadata accessible. This can be handy for several reasons, especially when one of our crucial services is no longer available.

The maintenance kill-switch in our case is implemented via an env variable that disables main features on the client and prevents unsolicited requests on the server.

const isMaintenance = process.env.FLAG_MAINTENANCE === SETTING_TRUE;

if (isMaintenance) {
  return new Response(
    'Sorry, the service is not available at the moment',
    {
      status: 429,
    },
  );
}

Server handling is the last resort in this case, so we coupled it with the rate limit checks, hence the 429 status.

There is also a noticeable message in UI informing of the ongoing work on the website:

Reporting

After a while Johan comes up with a new idea — the feedback loop for the recipes — to gather user insights and refine AI outputs. It makes a lot of sense, since we need more field data in order to improve our instructions. Furthermore, it’s sets up the stage for the new features, something like recipes library.

Fortunately, it’s also additive to our codebase.

Reports page will be located in the new admin area of the app. The most important piece of information is the recipe output. It needs to be easily accessible along with the input data and report information. We can browse reports and mark them as read or completed.

The reporting backend relies on CRUD operations using Next.js actions. The only tricky task to solve is how to identify and store the reports.

Since we don’t really want to use another DB or overhaul existing code, the simple solution is to create a new KV record based on the recipe ID. It naturally can be scaled further to accommodate more than 1 report per recipe, yet for our practical debugging needs it’s more than sufficient.

import { kv } from '@vercel/kv';

export const makeKVReportKey = (id: string) => {
  return `${id}-report`;
};

const getKVReportKeys = async () => {
  return await kv.keys('*report');
};

// create report
export async function addReportAction(newReport: ReportData) {
  const reportKey = makeKVReportKey(newReport.id);

  try {
    const reportData: ReportData = {
      id: newReport.id,
      comment: newReport.comment ?? '',
      // other data
    };

    // update actions is nearly the same, so we skip it
    await kv.hset(reportKey, reportData);
  } catch (e) {
    if (e instanceof Error) {
      throw new Error('Could not send the report');
    }
  }
}

// get reports
export async function getReportsAction(): Promise<ReportData[]> {
  let reports: ReportData[] = [];
  const reportKeys = await getKVReportKeys();

  for (const key of reportKeys) {
    const report = await kv.hgetall(key);

    reports.push(report);
  }

  return reports.sort((a, b) => (a.dateAdded > b.dateAdded ? -1 : 1));
}

// delete report
export async function deleteReportAction(id: string) {
  const reportKey = makeKVReportKey(id);

  await kv.del(reportKey);
}

You may have noticed certain simplifications for some operations.

The reason being is that “create report” is the only user-facing action. Other actions are rather contained and limited to local usage. However if you intend to inherit this approach, make sure to catch and log the unexpected errors for various app roles.

Unicornix 🦄

When Fuji X Studio just started, the color theme was inspired by Fujifilm brand green color with the sporadic red accents. The theme itself looked fine, but former approach could cause confusing workarounds for the accessible colors, especially when dark theme was involved.

The design challenges with Fuji X Studio inspired the creation of 🦄 Unicornix, which later became its theming backbone.

🚀 https://www.npmjs.com/package/unicornix

This transition resulted in a modern, versatile, and fully accessible UI:

Other design tokens are created with the help of Design Tokens Generator as usual.

🚀 https://www.design-tokens.dev

If you want to have a deeper look at the tokens organization, welcome to explore the design system starter project, specifically the relevant package. It’s essentially the one used in Fuji X Studio for theming.

Also, big kudos to Chakra UI for creating fantastic theming solution. It’s system prop approach is incredibly intuitive and it’s a struggle to switch back after working with it for a while. Highly recommended.

If you wonder about the name differences, someone snatched the fujixrecipes.com domain just a couple of days before I was about to commit a purchase. And you probably guessed what happened next — another pivot led to branding and content changes.

“Frankly, I like the new name better.”

“Johan, you are just happy that the project is complete.”

“No, see, «Studio» implies a professional photography environment”

“And «Recipes» are some sketchy things that you never follow?”

“Replacing ingredients is creative!”

“I wonder why it’s not yet in testimonials…”

Imprint

The Freemited

FUJI X Studio is entirely free — no ads, no signups, and no data sales. It’s designed for hobbyists and developers as an educational and creative tool. And it’s a fun project to work on.

🚀 https://www.fujix.app

At the same time it is relying on the high quality services like Vercel, Gemini and AWS S3, but respecting the virtual limits, imposed by aforementioned services. Luckily, given the predicted usage and rate limitation it’s fairly enough for hobby experiments.

Specs

FUJI X Studio is based on Next.js and powered by Vercel, featuring Chakra UI and Ark for the interface, Lucide icons, Google fonts, Design Tokens Generator and Unicornix for theming, AWS S3 for images storage, Gemini AI for images processing, Vercel KV for database. While additional services contribute to the project, this lineup offers a clear overview of the core stack.

NextJS 15? Chakra3?

In late October 2024, both Next.js and Chakra released major updates.

Coincidentally, just a couple of days before final polishing and launching the app, posing a precarious challenge of yet another tech update. After giving it a b/g/rief overview and estimating the migration effort it was decided to stay somewhat behind the bleeding edge for a while. It’s totally okay. Let it be.

Frame It

Fuji X Studio started as a spark of curiosity, and evolved through the proof of concept, researches, pivots, and finally emerged as a tool that bridges AI innovation with the practical experimental photography.

We certainly learned a lot through this journey, which resulted in this very article. Of course some parts were skipped otherwise the story would never end. Same goes for the app development, and can apply to the photo editing as well. You need to know when done is done. It’s the essential skill that gets honed with the every next project.

If you got some inspiration, had some fun, found something useful or new, please support the article via sharing or 💜. Thank you for reading!

“Hey, Johan, do you know what are going to do today?”

“Na ja, try to take over the world?”

“Wha…? Jeez. Let’s go take some photos first, shall we?”

Design System Starter Template - All Technology You'll Ever Need

Evgeny Khoroshilov — Thu, 15 Aug 2024 14:34:00 +0000

There are several ways how Design System can be founded — down-top, top-down, external, originated from design or development needs and probably some others. One thing is certain — it’s important to start things small, while keeping an eye on the future setup, which is crucial for sustainable growth.

The very foundation you build today must support current needs while being agile and thought through to suffice gradual evolution of requirements within a project or organization. This article focuses on the technical backbone, essential for creating a Design System that can satisfy expanding ambitions.

The 🚀 Design System Starter Template (DSS) is built on the core components that establish a strong technical foundation for scalable and maintainable Design System. These components ensure that design and development are consistent, flexible, and efficient.

⭐️ https://github.com/XOP/design-system-starter

In the following sections we’ll overview primary and secondary modules of the DSS template, as well as its services and tooling. In addition we’ll explore their cost-effectiveness in the early stages of Design System and their potential in more mature stages.

The Core Components

UI Library: The Heart of the Design System

The DSS UI library serves as the central pillar of DSS Template, built with react-aria to ensure accessibility-first, headless UI components. While React is the selected framework for the template, DSS is meant to be easily adapted to other frameworks like Vue or Solid. This adaptability allows teams to choose the technologies that best align with their project needs without being locked into a specific stack

For styling DSS UI relies on vanilla-extract, which provides a robust scalable zero-runtime CSS base. Yet again, it’s a flexible choice, allowing for alternative approaches like CSS modules, Panda CSS, Tailwind etc.

For stability, UI components rely on the testing library, focusing on functionality in the first place. Specific testing scenarios might not be relevant in case of themed (headless) components, but essential in other scenarios.

Resulting component structure looks rather straightforward:

Switch/
  index.ts
  Switch.css.ts       - styles created with vanilla-extract
  Switch.spec.tsx     - tests using testing-library
  Switch.stories.tsx  - documentation with Storybook stories
  Switch.tsx          - component based on react-aria

It’s worth mentioning that even though DSS UI is not following a multi-package approach, it still allows for tree-shaking, leveraging respective rollup options in Vite config:

// named import
import { Button } from '@ds-starter/ui';

// default import
import Button from '@ds-starter/ui/components/Button/Button';

A critical aspect of the UI library is the early incorporation of Design Tokens. Tokens are foundational to maintaining consistent styling across Design Systems, allowing even projects that do not utilize the full UI library to benefit from a cohesive design language. With the proper semantic tokens in place, colors can be easily changed without the need for massive refactoring. Also, with the modular approach we don’t really care how Design Tokens are built, but rather what is being output.

Design Tokens: The Backbone of Consistency

Design Tokens are integral to the consistency and flexibility of the Design System. They provide a standardized approach to theming and styling across all modules and applications, ensuring that every element of the UI remains cohesive.

DSS color tokens are generated using 🦄 Unicornix, a tool that allows to create accessible and customizable color palettes, providing for easy start with light and dark modes. Typography and some other tokens are created with 🎨 Design Tokens Generator. Altogether this provides a solid foundation for further scaling without encountering major roadblocks.

unicornix - npm

Unicornix - themeable and accessible color palette generation. Latest version: 0.7.0-beta.0, last published: 9 days ago. Start using unicornix in your project by running `npm i unicornix`. There is 1 other project in the npm registry using unicornix.

npmjs.com

DSS Tokens are available in both CSS and JavaScript formats, to reflect and support different project needs, from simple websites to complex web applications. Theming can be done in several ways, and here we fully rely on CSS custom properties.

Here is an excerpt from the generated CSS.

It’s easy to note that theme can be swapped completely by changing a single data attribute:

:root[data-theme="light"], [data-theme="light"] {
  --awsm-color-content-strong: rgb(24, 26, 27);
  --awsm-color-content-regular: rgb(45, 47, 49);
  --awsm-color-background-regular: rgb(255, 255, 255);
  --awsm-color-background-subtle: rgb(236, 237, 237);
}

:root[data-theme="dark"], [data-theme="dark"] {
  --awsm-color-content-strong: rgb(255, 255, 255);
  --awsm-color-content-regular: rgb(229, 230, 231);
  --awsm-color-background-regular: rgb(0, 0, 0);
  --awsm-color-background-subtle: rgb(9, 10, 11);
}

JS tokens can be consumed as CSS refs, containing the references to values, rather than the color strings. This approach is great for semantic variables and theming without sacrificing performance:

export const tokens = {
  content: {
    strong: "var(--awsm-color-content-strong)",
    regular: "var(--awsm-color-content-regular)",
  },
  background: {
    regular: "var(--awsm-color-background-regular)",
    subtle: "var(--awsm-color-background-subtle)",
  }
}

Icons and Fonts: Modular Visual Language

The Icons and Fonts modules add depth to the visual language. Icons are managed through an efficient process that generates components from SVG files using SVGR and tsup. This ensures that icons are consistent and can be flexibly integrated across the system.

Similar to UI components, icons can be also imported individually:

// named import
import { IconX } from '@ds-starter/icons';

// default import
import IconX from '@ds-starter/icons/lib/IconX';

// Source (SVG) import
import IconXSrc from '@ds-starter/icons/svg/x.svg';

The Fonts package offers a convenient solution for managing typography within the Design System. It supports both base64-encoded fonts for quick setups and Google Fonts integration for more robust implementations, giving teams the flexibility to choose the best approach for their project’s needs while maintaining consistent typography across all digital products.

It’s worth noting that while base64 encoding is efficient, it’s not effective for production setup. Yet in the early stages it can be a common denominator for consistent typography. Of course going further this should be replaced with the more appropriate fonts-loading strategy.

Now, the question arises — should you setup Icons and Fonts packages from the start? The answer naturally depends, however in most typical scenarios it will be a “no”. More agile environment in the early stages is crucial and less dependencies is the key. Yet, keeping in mind the upcoming structure and incorporating that in the early setup is a good idea, shaving off a couple of dozen “story points” in the future refactorings.

Documentation — Storybook and Beyond

Storybook: A Multi-Purpose Development Tool

Storybook is an important tool for UI development, serving primarily as a development environment and a documentation portal on early stages of Design System. It allows to visualize and interact with UI components in various states and configurations, resolving issues early in the development process.

Storybook in DSS is a standalone app that does not itself host any stories — they all are collected across the packages and composed in one central hub. This way DSS Storybook can document color palettes, typography, iconography etc. along with the UI components from different sources after a simple setup.

💡 Note that there is no storybook composition per se,

yet it’s also possible as one does not deny the other.

Explore the deployed demo here: https://ds-starter-storybook.vercel.app/

Beyond its direct functionality, DSS Storybook is additionally equipped with Visual Regression Testing (VRT) and Accessibility Testing using Playwright. Such automation is essential for large design systems, where manual testing could quickly grow ineffective and time-consuming. By integrating these tests into the development workflow (early), DSS ensures that the Design System can evolve fast without fear of regressions.

While being an irreplaceable tool for early-stage documentation, consolidating component documentation and visual examples into a single platform, Storybook is not actually a documentation website. With time, more sophisticated, content-oriented and customizable solution is demanded, especially for the Design System consumers far apart from technology.

Documentation Website: Design System Knowledgebase

As the Design System matures, the need for more detailed and accessible documentation becomes paramount. The DSS Documentation Website (DSS Docs) addresses this need by providing a dedicated application for organizing and presenting information about the Design System.

Explore the deployed demo here: https://ds-starter-docs.vercel.app/

DSS Docs is designed to be minimalistic yet highly functional and customizable. It includes several modules that can be tweaked and modified to meet the project purpose. Powered by Astro and enhanced with nanostores state manager, DSS Docs implies two main types of content: Articles and Component Documentation.

Articles offer in-depth insights into Design System concepts, provide guidelines, patterns and describe foundational layers in detail. To add a new Article is as easy as simply to place a Markdown file into the respective folder.

Component Documentation includes interactive examples dynamically loaded from the Storybook stories. This integration solves a couple of issues — it ensures consistency across the “Dev” and “Prod” documentation and avoids redundancy in content creation.

💡 As a bonus — component examples can be edited in the UI library and will be automatically picked up by Docs running in dev mode. Not a Storybook replacement, but can be useful for cosmetic updates.

New Component Documentation can be added with a MDX file, following a particular schema. Apart from the main description, extra sections can be added following the “Usage” pages example.

Expandable structure of DSS Docs allows for easy updates and tweaks, making it an essential tool for teams looking to step up from Storybook without significant effort and creating redundancy. The Documentation app is themed with DSS Tokens to ensure a consistent look and feel of the main product.

Automation and Workflow Best Practices

Scripts and Github Actions Automation

DSS leverages a series of scripts to handle essential tasks like testing, linting, formatting, and dependency management. Turborepo offers great help for running scripts effectively, especially when every module adheres to a unified standard.

What’s more, everything that we run locally, including Visual Regression Testing — can be done on CI, thanks to Github Actions. Apart from the thorough quality checks, Github Actions will take care of apps deployment too (powered by Vercel). Naturally, all scripts are configurable and optional.

Changelog and Release Management

DSS uses Changesets to automate the processes of changelog generation and packages releases, ensuring every change is tracked and properly versioned. Needless to say, both processes are supported by Github Actions as well.

Here are some examples of published NPM packages:

Component Generator

To further enhance productivity, DSS includes a Turbo-powered Generator that simplifies the process of scaffolding new UI components. Apart from saving time, this allows to greatly reduce the human-error-copy-paste factor.

# Run a generator
$ pnpm run gen:ui

After replying to a series of prompts, you will get the following:

New component scaffolded in the DSS UI package, containing all respective files
Same component added to the DSS Docs application, with the correct MDX frontmatter data

Like almost everything in DSS, generator template can and most probably need to be tweaked to the project needs. This is a completely arbitrary operation, however using generator can be very beneficial for contributors, onboarding of team members and scenarios like codebase migration.

Flexible Technology Stack

Main Design Principle

Design System technological stack is an arbitrary matter, however it’s for sure not random. It’s a natural effect of multiple contributing factors, including, but not limited to:

product scope and project peculiarities
initial size and future ambitions
teams expertise and proficiency
contributors and consumers proficiency
client requirements and technical stack
overall codebase age and historical reasons
existing technical debt
cross-platform and cross-browser support
maintainability requirements
existing or upcoming deadlines
industry trends and market volatility
organization structural changes
and more…

💡 Would you be interested in a dedicated article on this? Let me know!

⭐️ Also, you are past 2000 words, reading champion!

The aim of the DSS template is not to comply with every single scenario, but to suggest the industry average best practices that can be further tailored to the desired experience. Understandable, Template won’t fit a lot of systems, however presented patterns and snippets can be explored, re-used, improved and hopefully inspire new creations.

Selected, Recommended, Opinionated

Throughout the article we observed multiple technologies being used in order to compose the DSS Template and provide a holistic and functional developer experience. Actually, there’re more under the hood, welcome to explore the comprehensive documentation.

Those technologies can be basically grouped into “Selected”, “Recommended” and “Opinionated” categories, so that each next one is more biased than the previous.

Consider examples:

React is Selected for being the most popular solution for UI libraries, it’s perfect for demonstration of UI library scaffolding.
React-Aria is Recommended, because it’s the headless UI solution that prioritizes accessibility; we don’t need to invent the wheel with typical functional patterns and get lots of accessibility concerns sorted out of the box.
Using Biome for linting and formatting is an Opinionated choice (I appreciate the turn-key configuration and blazing performance) and can be replaced with ESLint and i.e. Prettier.

Of all other technological choices I would like to (additionally) highlight the Opinionated ones:

Vanilla-extract as the CSS solution is great for scalable projects that prioritize performance and server-side rendering compatibility. While it has a somewhat higher entry threshold, it provides a very friendly CSS-in-JS experience without CSS-in-JS downsides.
Nanostores is the go-to solution when it comes to minimalistic and effective global state management in the apps. It shines in the island-like architecture and Astro projects in particular. DSS Docs feature nanostores for basic operations like toggling theme or source code, but it’s capable of managing much more complex tasks.

Finally, Typescript is the technology that stands out being in all three groups simultaneously. It has been around for a while to become industry standard, it is generally recommended for complex projects like Design System and I would also use it further for similar reasons.

Closing Thoughts

Building any product requires a solid foundation, a clear roadmap, careful preparations, and timely revisions at every milestone. As requirements evolve over time, your technology should be resilient enough to adapt effectively to new settings.

With Design Systems, it’s all of that, plus the element of perpetual motion. Can you think of a universal development approach that can handle project unpredictability and versatility beyond the good ol’ Markup and Style? Maybe later, but for now, this is just the way of things.

The 🚀 Design System Starter Template can help you in establishing a strong technological core and may even become a great starting point, providing a modular and flexible solution for your next Design System challenge. However, for the most part, it’s the groundwork for insights and sparks of inspiration. This has happened to me several times during the development of DSS to the extent of pivoting on tools, which is why I think it’s useful. I’m definitely looking forward to and inviting you to the next encounters.

Design Systems Consolidation

Evgeny Khoroshilov — Mon, 25 Mar 2024 12:27:00 +0000

Let's say you are working on a set of tools for your colleagues, it's getting traction, projects are built faster, your team grows and you decide it's time to make the right thing - make this the official Design System. The word spreads, you talk to the upper management and find out there are other similar initiatives in the company. Incidentally, one System exists for ages already, but your departments are so far apart you never knew. The other System is a niche thing, they use a different frontend framework for particular reasons. Oh, and they also have components for mobile platforms.

Your head starts to spin, you are not alone who have been working on the Design System establishment! After a breather some new feelings and realizations emerge. What happens now? In a quarter? After a year?

If this sounds familiar you've probably been there, or you might be there now while you are reading this. Worry not, you are on the right track. In this article we'll explore the scenarios of the upcoming potential developments of the Systems organization.

To be fair, this multi-system case is not as rare as it may seem. Different teams serving different projects with different business value, historical reasons, budgeting, resources, time allocation, people expertise, stakeholders support etc - produce independent varying Design Systems over time. There can be many similarities, but there will never be a total match, and that's ok. Then of course, time is another factor. Huge team of experts won't build a Design System of the same degree of maturity in 3 months as a moderately developed team would do in 3 years.

Over time leadership may (will!) come up with an idea of consolidation. For a number of reasons, of course, however something is pretty much on the surface - it's what Design Systems were built for! Overcome challenges at scale - less effort duplication, less resources spent, less redundancy, higher consistency. Sounds almost too easy, because it's surely not. And it may even get gnarly when independent systems prefer to stay independent...

A Schroedinger's System

So where do things go from here? Well, there are Options. Abrupt decision is a bad decision. Everything should be considered, analyzed, weighted and potentially POC-d in some cases. The final outcome is unique to your organization's circumstances and aspirations. Can it go back to the starting point? It sure can! Should we prepare for a 2.5-year-long migration? Maybe we should! At this point, it's like System appearing in superposition.

And yet, potential developments are known to the extent. What's more, a lot of companies have been through similar challenges already and their experience is invaluable.

Knowledge is power. Equip for the journey.

Options and Examples

Let's have a look at the challenges that your organization might be facing with the help of a real-world analogy.

Imagine an automotive conglomerate that operates multiple car brands, each serving different market segments but under the same corporate umbrella. Each brand has developed its unique way of building cars, utilizing different engineering teams, technologies, and suppliers. However, to optimize operations, reduce costs, and leverage synergies, the conglomerate considers strategies to consolidate its manufacturing and design processes while still catering to its diverse market segments.

We'll now explore several options of further advancement, each highlighting pros, cons, risks, costs and "quick wins", that aim to tactically improve the current situation.

Option 1: Systems Continue Work as They Do

In this scenario, the automotive conglomerate allows each of its car brands to operate independently, utilizing their unique manufacturing processes, technologies, and market strategies. Each brand caters to its specific segment - luxury, economy, sports, etc. without altering their individual operations. This approach maintains brand identity and specialization but may lead to redundancy in research, development, and production across the conglomerate.

Pros: Each brand maintains its unique identity and specialized market focus. Innovation and experimentation are less restricted by overarching constraints.
Cons: Duplication of efforts and resources across brands leads to inefficiencies. Opportunities for cost savings and standardization are missed.
Risks: Stagnation due to a lack of collaboration and knowledge sharing. Potential to fall behind competitors who optimize their operations.
Costs: Same, for maintaining separate development, production facilities, and support systems.
Quick Win: Cross-brand communities of practice to share knowledge and best practices without altering existing structures.

A good example of this approach is Apple, which continues to develop macOS and iOS separately, catering to desktop and mobile markets with distinct systems. Although there are crossover features, the platforms remain independent.

This option may seem like nothing happens from a practical perspective. However, it's incorrect to say there are no changes - while going through comparison and analysis, systems, stakeholders and leadership acquire a lot of knowledge. Sure, systems' status quo holds for now, but this information allows us to strategize over different areas of development. And most probably over time there will be other improvements and re-evaluations.

Option 2: Systems Start Sharing Subsystems

Here, the conglomerate first identifies commonalities between its brands, such as the need for safety features, infotainment systems, or engine components. It decides then to consolidate these into shared subsystems, developed centrally and then deployed across different car models and brands. This initiative reduces costs and streamlines operations while still allowing each brand to maintain its unique market positioning. Brands start benefiting from advancements in technology and design innovations developed by their sister brands, promoting a culture of knowledge sharing and efficiency.

Pros: Efficiency gains from reusing components and knowledge across brands. Potential for a unified quality standard.
Cons: Challenges in aligning different teams' priorities and methods. Risk of diluting brand identity.
Risks: Resistance from teams accustomed to working independently. Integration issues between disparate systems.
Costs: Moderate, investments in integration and standardization upfront but savings over time.
Quick win: Shared organization of common components, like infotainment systems or safety features.

Some time ago Adobe transitioned its standalone desktop applications into an integrated suite known as Adobe Creative Cloud, allowing for seamless file and setting synchronization across different Adobe software. This shift enabled designers to work more fluidly between applications like Photoshop, Illustrator, and After Effects, effectively sharing subsystems such as cloud storage, font management, and asset libraries.

In the context of a Design System environment instantaneously one thinks of Design Tokens or other forms of system foundation and brand uniformity. You can also consider a common Documentation library, shared Accessibility best practices, Voice and Tone guidelines and more along these lines. From a technical perspective think of unifying the platform solutions, like release processes, assets distribution etc.

Design Tokens Generator - For Web Developers and Designers

Streamline your design system with Design Tokens Generator for web development and design. Get efficient and consistent design elements effortlessly. Try now.

design-tokens.dev

Option 3: Systems Retire and a New One Emerges

To continue with analogy, the conglomerate decides to phase out several of its older, less efficient car brands or models and launches a new brand or model line that incorporates the best technologies, processes, and market strategies learned from the entire group. This new brand is built from scratch to address current market demands and technological advancements, aiming to replace the older ones progressively.

It's a bold move, involving significant investment and a strategic overhaul, but it's aimed at ensuring long-term relevance and competitiveness in the market.

Pros: Opportunity to build from the ground up with modern practices and technologies. Can address legacy issues.
Cons: Significant upfront investment. Risk of disruption to current operations and customer experiences.
Risks: Adoption resistance, both internally and from existing users. Potential for project delays and overruns.
Costs: High, both in development and in transitioning users and staff.
Quick Win: Pilot programs to test and refine the new system before a full rollout.

In 2014 Google announced a transition from AngularJS to Angular. It was a significant shift spanning more than 1600 applications that involved retiring the old framework in favor of a new one built from the ground up, considering modern web development practices.

Once again, it is quite a bold move, and even more bold if done at once, as that would be similar to pulling the hand brake at 200km/h on the autobahn. Apart from investment and thorough planning, this strategy cries for RFC, POC, probably a couple, maybe a dozen. And a carefully organized roadmap, transitioning from here to then and following the milestones. Depending on the organization size it can take years, and even after that you may find some outdated pages in your apps, simply due to the cost efficiency.

More lean strategy may involve transition to the state in "Option 2" first and re-evaluate some time later. It may happen that this step would be satisfactory enough.

Option 4: One System Stays and Others Retire

After a thorough assessment, the conglomerate decides that only the most advanced, efficient, and market-responsive brand will continue its operations as before. The other brands will gradually be phased out, with their best features, technologies, and market strategies being integrated into the surviving brand. This could mean, for example, that a high-efficiency engine developed for a luxury brand is adapted for use in economy models, or a successful design language is adopted across the board. This process includes retraining staff, retooling manufacturing processes, and transitioning the customer base to adopt the products of the consolidated brand.

Pros: Streamlines operations by focusing on the most successful or advanced system. Encourages uniform quality and experience.
Cons: May not meet all unique market segment needs. Could discourage innovation in the absorbed systems.
Risks: Alienation of customers and teams attached to the retiring brands/systems.
Costs: Moderate to high, depending on the scale of integration and rebranding efforts.
Quick Win: Integrating branding and marketing efforts for a smoother transition and unified customer experience.

In the tech world, Adobe's decision to discontinue Flash in favor of HTML5 is a pertinent example. Over time, Flash's limitations became apparent, including security vulnerabilities and lack of support on mobile devices. HTML5 offered a more secure, efficient, and flexible alternative, leading Adobe to announce the end of Flash support by the end of 2020. This shift required developers and content creators to migrate their content to the newer, more sustainable HTML5 standard.

💡 If you feel nostalgic, check out the ruffle project - the open source and safe Flash player emulator

Choosing this approach can get quite nuanced if none of the systems shines bright enough to overshadow others. In practice that could mean lack in one or some disciplines with solid advantage in the others. For example, great specialists without dedicated time allocation, stable and developed UI library minus the accessibility practices, or excellence in all tech areas, except the library framework is a couple of generations behind.

Naturally, to proceed with one system, it should stand strong so it can be formed based on the best suitable choice, plus the best or lacking disciplines from the other systems (hybrid approach).

To the Next Steps

Consolidation discovery requires patience, meticulous planning, and an openness to gradual progress, due to the inert nature of large-scale organizations and overall complexity. It can be very challenging to align different departments and systems due to established processes and the scale of existing operations. This inherent inertia means that consolidation is not a switch that can be flipped overnight. It's something that might unfold over several years or, in some cases, might lead to the realization that complete consolidation is not the optimal solution after all.

Design Systems Beyond Basics: Unveiling Nuances and Oversights

Evgeny Khoroshilov ・ Oct 16 '23

#design #designsystem #productivity

This is why the initial step in this journey is a comprehensive analysis and feature comparison of the existing systems. This foundational work is critical, as it sets the stage for informed decision-making regarding the future of the organization's Design Systems. Further, the organization may proceed with drafting RFCs, developing POCs, or even forming new teams dedicated to lead the consolidation effort.

These steps are not trivial, they require significant investment in terms of time, resources, and commitment from leadership and stakeholders across the organization. However, armed with a clear understanding of the potential options ahead and drawing on the experiences of others who have navigated similar challenges, organizations can approach the task of Design Systems consolidation with greater confidence and clarity.

Acknowledgment

This article is heavily inspired by the work of Nathan Curtis. If you haven't read it yet, please indulge yourself!

How to build AWSM docs with Storybook and Astro

Evgeny Khoroshilov — Mon, 26 Feb 2024 11:42:00 +0000

Introduction

In the dynamic realm of UI development, a well-documented design system is the key to success. Welcome to the AWSM Docs - a slingshot approach to get your Design System documentation website up and running in no time. In this short article, we'll delve into leveraging Storybook and Astro capabilities in order to save time on documentation effort and maintenance.

Idea

Storybook and Astro is the dynamic duo behind the AWSM Docs powerful synergy.

Storybook acts as an interactive playground for UI components, while Astro builds and enhances a static website with dynamic capabilities. Together, they empower UI library development. And the best part is - you get documentation website at (almost) no additional effort.

Of course Storybook alone can serve as a documentation website, especially at the early stages of Design System development, however it is limited in terms of customization, and rather opinionated in the sense of information architecture. Let the tool remain the tool for its purpose and embrace the beauty of the dedicated documentation website, which can further become a single gateway for information about your Design System.

Bid farewell 👋 to the challenge of maintaining consistency between stories and doc snippets. AWSM Docs approach eliminates redundancy and ensures your documentation mirrors the current state of your UI library or/and Design System.

Setup

Project structure is quite standard and straightforward. It's a pnpm-based monorepo, additionally enhanced with nx and a couple of formal configurations.

Feel free to explore the repo and read along.

packages/awsm-ui represents the UI library that needs to be developed and documented. Development premises are provided by Storybook, located in apps/storybook. Separate Storybook app is the best solution for scalability, as it can consume stories and MDX files from different packages. This is particularly useful for the modularized libraries, but even without that it offers a more clean code structure thanks to separation of concerns.

Next to Storybook sits the apps/docs app, (auto-)documentation website built with Astro, the primary subject of this article. To mimic a real-life Design System website it has a formal structure and some demo pages, traditionally in the form of MD files. The only thing it does not have is the coded UI examples. Interesting. We'll delve into details shortly.

And last but not least, apps and packages depend on the custom Design Tokens, exported by packages/awsm-tokens. Note that there are two exported themes, suitable for both light (⚡️ electric) and dark (🦄 ultraviolet) color mode preferences.

UI Library

At this point it's worth mentioning that there are a lot of things in this project "for demo purposes". Sure. I am not totally opposed to the idea of using three different headless libraries for building a perfect UI, there can be more - yet sanity is the limit.

For the same reasons I selected React as the framework for the task. Love it or hate it, numbers are talking, not to mention the foundational support of its full-stack endorsers - NextJS and Remix.

In awsm-ui you may find the 3 amigos components, each based on a different headless UI library (and I'm not going to repeat that further - for demo purposes):

(mandatory) Button - based on React-Aria - represents the atomic component, entity with the simple structure
Switch - powered by Radix UI - atomic component with internal state and slightly more complex structure
Disclosure - featuring Headless UI - more of a molecule kind... perhaps because it's bigger

All components are styled with vanilla-extract styling engine, effectively utilizing Design Tokens in JS format. Remember the (demo) purposes? Definitely applies here as well. Nothing is stopping you from using any other CSS magic of choice.

As mentioned, all components are documented with Storybook (v^7.5). There is nothing fancy about the stories or config organization, as I try to keep things clear, unopinionated and ready for further tweaking.

Here's a slightly reduced example of the Switch stories file:

import type { Meta, StoryObj } from '@storybook/react';

import Switch from './Switch';

export default {
  title: 'Form/Switch',
  component: Switch,
} satisfies Meta<typeof Switch>;

type Story = StoryObj<typeof Switch>;

export const Base: Story = {
  args: {},
};

export const Checked: Story = {
  args: {
    ...Base.args,
    defaultChecked: true,
  },
};

export const ColorPrimary: Story = {
  args: {
    ...Base.args,
    color: 'primary',
  },
};

As we'll see further, more complex examples using templates and render: are also supported, so it's not limited to plain args.

The Docs

Overview

Now let's explore the docs app. In the project I'm using Astro v^4.0, and at the time of writing it's already updated to 4.4, however no breaking changes are expected, so feel free to use the latest version.

In a nutshell, resulting app consists of the home page, couple of content sections - Core and Patterns, each containing an introduction and several inner pages, and the Components section, hosting static and dynamic documentation for the UI library.

App is structured in the following way:

src/
    client
    components
    content
    data
    layouts
    pages
    shared
    store

client contains the client:only components, i.e. CopyButton
components comprises traditional Astro building blocks
content is the required element of the Astro Collections, structured and filled in accordance with the navigation and website contents
data contains some additional MD(x) files for the section pages
layout and pages are standard and self-explanatory
shared hosts various utils and hooks
store is the optional state management layer, powered by nanostores

Collections

It is worth exploring collections and respective navigation for a little bit, as there is quite a high chance this will be expanded and customized. Luckily, it is actually quite simple.

The easiest way to get familiar with the navigation structure is to check out shared/globals.ts - there are a couple of constants that work in sync with the collections. For example the "Core" section needs the following:

// collection of documents
content/core/*.md

// shared/globals.ts
NAVIGATION_KEYS.core = 'core';
NAVIGATION[0] = { slug: NAVIGATION_KEYS.core, title: 'Core' }];

And that's it for the basic collections!

Now, for the most interesting and challenging part.

Components

Components documentation is basically split into "static" and "dynamic" parts. "Static" part is imported from the dedicated content collection, whereas the "dynamic" part is loaded directly from the UI library.

The easiest way to follow how this alliance works is to start with the pages/components/[...slug].astro.

Here's the part we need:

// pages/components/[...slug].astro excerpt

---
const { entry } = Astro.props;

stories = await import(`../../../../../packages/awsm-ui/src/components/${entry.data.dir}/${entry.data.component}.stories.tsx`);
examplesData = refineStories(stories);
---

<Examples 
  data={examplesData} 
  name={entry.data.component} 
  dir={entry.data.dir} 
/>

First, we get the current Component entry data, defined in the frontmatter (we'll get back to that later).

Second - we dynamically import and pass the stories data to the Examples component.

Note, that it is a server call and this data will be used further for rendering "slots" with names and other meta information in Examples:

// components/Examples.astro excerpt

---
const { data, name, dir } = Astro.props;
---

{data.map(([exampleName]) => {
  return (
    <Example heading={exampleName}>
      <ExampleContent
        client:only
        name={exampleName}
        componentName={name}
        componentDir={dir}
      />
    </Example>
  )
})}

Evidently, it's a simple presentational component. The one we are actually looking for is ExampleContent - let's dive in for a closer look.

ExampleContent is meant to be loaded on the client, this is where the dynamic heavy lifting happens. What we need from the stories are in fact the stories themselves - most typically the component variants, rendered with the different props.

💡 Everything that we need for successful rendering can be found within the stories. Depending on the story format we might need different data.

// client/ExampleContent.tsx excerpt

const ExampleContent = (props: ExampleContentProps) => {
  const { name, componentName, componentDir } = props;

  const [struct, data, isLoading] = useStoryLoad(name, componentName, componentDir);

  const { component: AnyComponent } = struct;
  const Component = AnyComponent as JSX.ElementType;

  let Variant;

  if (data.render) {
    if (data.args) {
      const Template = data.render as JSX.ElementType;

      Variant = () => <Template {...data.args} />;
    } else {
      Variant = data.render;
    }
  } else if (Component) {
    Variant = () => <Component {...data.args} />;
  }

  return <Variant />;
}

Here, struct is an arbitrary term for the default object and it's contents look somewhat like this:

default: {
  title: 'Form/Button',
  component: {
    '$$typeof': Symbol(react.forward_ref),
    render: [Function: Button]
  },
  parameters: { layout: 'centered', docs: [Object] },
  tags: [ 'autodocs' ]
},

Naturally, having Variant data we can render the source code if needed.

Finally, let's have a look at the loading hook, however you won't find anything exceptional there, as it's pretty standard and predictable at this point. Note that struct is not mentioned here, as it's almost identical to the name import.

// shared/hooks/useStoryLoad.ts excerpt

export const useStoryLoad = (
  name: string,
  componentName: string,
  dir: string | undefined
): [ComponentStruct, Story, boolean] => {
  const componentDir = !!dir ? dir : componentName;

  const [data, setData] = useState<Story>({});

  useEffect(() => {
    async function load() {
      const { [name]: _data } = await import(
        `../../../../../packages/awsm-ui/src/components/${componentDir}/${componentName}.stories.tsx`
      );

      setIsLoading(false);
      setData(_data);
    }

    load();
  }, []);

  return [struct, data, isLoading];
};

Binding

We explored the main mechanism behind component examples rendering, and now it's time to get back to the documentation part.

Components collection represent the static part of the documentation and organized in a particular way:

content/
  components/
    <ComponentName>/
      index.mdx
      [usage.mdx]
    ...

index.mdx contains the introductory information about component, whereas usage.mdx is optional and may contain the docs about component application. If you wish to extend this structure with any custom pages, i.e. "Accessibility", it's easy to do. Check out the following files and adjust data accordingly:

shared/globals.ts - update COMPONENT_NAVIGATION
components/Sidebar.astro - look for the currentSlug

What is important about both files is the frontmatter data, usage of which you could already notice in the pages/components/[...slug].astro file. We can define the schema ourselves and should follow it in all documented components:

---
title: 'Button'
page: 'Examples'
group: 'Form'
component: 'Button'
dir: 'Button'
---

Here:

title - is the name of the component in the docs
page - is the name of the tab in the same docs
group - is the custom arbitrary grouping of components; see the usage in the components/Sidebar.astro
component and dir is what we actually use for the stories import

Gimmick

There's one more thing. It's more of a 🎁 bonus, actually.

Since we rely on the dynamic imports, Astro and Vite will automatically update components on changes - both components' and stories' code! It can give you extra flexibility on documenting (and sometimes updating) components, especially if you decide to output them in different example containers.

Conclusion

AWSM Docs presents a pragmatic approach to UI library or Design System documentation website development. While not claiming to reinvent the wheel, this solution aims to speed up and streamline the process. As with any tool, there's room for improvement, and I encourage further exploration.

It's worth noting that at the time of writing there's an upgraded and enhanced version of awsm-docs being prepared, stay tuned for another article!

Check out the project on GitHub and tailor the solution to your specific needs. Your insights and contributions will undoubtedly contribute to the evolution of this approach.

Happy coding and documenting!

Design Systems Beyond Basics: Unveiling Nuances and Oversights

Evgeny Khoroshilov — Mon, 16 Oct 2023 16:15:00 +0000

The domain of Design Systems now is quite saturated with articles, books, insights, and post-mortems, each offering a glimpse into the multifaceted landscape. Since dipping my toes into this realm in 2017, I've experienced various evolution steps within different organizations, witnessing firsthand the maturation of tools and processes. With the teams we've been through various evolution stages and to this day, our created Design Systems are alive and well.

While Design Systems have, in many respects, become a well-known initiative and occasionally an industry standard, overall system establishment isn't free from misconceptions that can misguide even proficient teams and companies. So in this essay featuring longer sentences and 0 button pictures, I would like to explore the ever-evolving Design System trends through the prism of practical experiences, focusing on the not-so-evident aspects. As in the end...

“All happy families are alike; each unhappy family is unhappy in its own way.”

― Leo Tolstoy, Anna Karenina

Let's course together through Design System definition, composition, benefits and, naturally, caveats.

A Design System Defined

In its essence, a Design System is a meticulously curated library, encompassing tokens, styles, components and many other digital aspects, guided by clear standards and accompanied by documentation. Fostered by a dedicated or federated team, it serves as the unseen engineer behind multiple products, orchestrating a harmonious digital user experience.

The well-aged Design System is sitting robustly between Brand Direction and Digital Experiences while orchestrating the Target Audience's journey. Eventually, it becomes an integral, cohesive, and structural layer within an organization, not only implementing but defining product and organization design vision.

Regardless of the requirements, resources, deadlines and ambitions, it's crucial to remember the key point - it should

always

start

small.

Design System pillars

Hello, myself from 2019. That was the year when I coined the term "three pillars" of the Design System. Though slightly adjusted over time, I can confirm the concept is still legit in one or another form. Recently I stumbled upon a resemblance of that model in Ben Callahan's course.

In short, the three pillars are Deliverables, Maintainers and Processes. Here's the metaphor in action - when one of the pillars is wobbly or crumbly, the Design System either stumbles or collapses under pressure, becoming a blocker instead of the intended purpose. Not to mention when there's just one pillar on its own - that should be either a dawn or soon decline of the initiative.

Side note - I'm not married to the "pillars" metaphor so much any longer, so let's come up together with a more viable and illustrative analogy (comments below).

Deliverables

With deliverables, it's rather obvious where to start and what to prioritize (UI libraries in any form) yet there are so many versatile options. Self-documenting libraries in Storybook, Figma-only documentation, code as the source of truth and more and beyond. Generally, there are 2 important things to focus on - Components and Documentation if you prefer alphabetical order. Documentation and Components if you are really being serious.

Code: Including UI libraries, design tokens, iconography.

Design Assets: Think Figma libraries and UX patterns.

Documentation: Spanning websites, code repos, Confluence etc.

Additional Assets: Illustrations, fonts and such.

Maintainers

Maintainers establish and move the Design System forward. These dedicated individuals and/or teams champion its evolution in the beginning and sustain the fidelity and reliability of the system later. They ensure it adapts and resonates with time, project and organization requirements and the landscape of technology and user expectations.

The more traditional approach in the early years - Design System originates from the design environment and is pushed forward by designer(s). The frontend-first approach was considered a rarity. Lately, there is no big distinction between the two takes, in fact - coordination of minds and efforts would work the best. If you need a deep (much deeper) dive into the topic of people behind Design System development, refer to Nathan Curtis's article.

Designers: mandatory.

UI developers: mandatory.

Recommended ratio?

A) Highly depends. Usually a good start would be 2+ frontenders per 1 design specialist.
B) Scale is non-linear. When in doubt refer to A).

Other competencies may include but not limited to:

UX designers
Accessibility specialists
QA engineers
Motion designers
Content editors
Icon creators (this is a real thing)

What about the Product Manager? Applicable to Design Systems this role is highly versatile without traditional boundaries of the industry, ranging from roadmap communication to fully-fledged architecture. It's worth mentioning that the weight of PM responsibilities can be owned or even shared between key maintainers, especially at the early stages. However, a dedicated role can help to push the envelope faster and assist with the priorities churn, miscoordination, excessive bureaucracy, red tape and other fun aspects of large or conservative companies.

Processes

Processes signify the operational backbone of a Design System. They are Lebowski's valued rug, tying everything together with routines, workflows and collaborations and ensuring integration of the Design System within the organizational framework. They come especially useful at later stages, however, it's highly advised to consider at least the basic ones in advance.

Another point of consideration is automation. You would like to save some precious time, wouldn't you? Automate everything possible, but avoid de-humanization pitfalls. Talk to customers and each other first.

Request and Update Cycles: It is crucial to establish and hone those as soon as feasible. For the team, it's velocity and transparency, for customers - trust and reliability.

Customer Support: Next in line - support - both technical and design-wise. Slack works for the most part!

Contributions: Prepare your fundamentals and encourage collaboration. Early insights are solid gold. Not too early though!

Onboarding: Your system would definitely benefit from a regular guided process, considering how it can change over time.

Office hours: When Slack doesn't work. Have a weekly or 2-weekly session to chat and answer questions, provide support and announce something cool. Agenda is the key.

Features of a Design System

Most integral elements that constitute a Design System are well known and I won't be going over them in detail again. Some less prominent building blocks might be overlooked though, so take a glimpse. Please note, that the list below only shows the median slice of features, simply because not all Design Systems mature to the level of delivering not just elements, but the whole parts of the application as micro-frontends.

Visual Style: The aesthetic glue binding the UI.

UI Components: Reusable design elements ensuring efficiency.

UX Patterns: Crafting a consistent user journey across platforms.

Accessibility: Embedding inclusivity from the get-go.

Editorial: Sculpting the tone and content consistency.

Charts: Standardizing visual data representation.

Plus more, should maturity and organization specifics demand for!

Features really shine when 3 pillars of the Design System are working cohesively. Some of them may seem to match the deliverables, but essentially it's a more conceptual and product-oriented list. For example, "Accessibility" can be achieved by putting together coding practices, inclusive design assets and guidelines, practical documentation and tutoring sessions. Take an element away and it falls apart. What is the value of high-contrast design if it's not respected in code? What is the value of aria props if they are neglected in the customers' projects? In both cases, it's a value multiplied by zero.

Compare this to the steadier and slower but holistic approach. Yes, not all code components are compliant yet with WCAG 2.1 AA, but they match good practices in design and product teams know how to apply and test for accessibility. The value would not be 10/10 from the start, but it's more than 0.

Finally, fully-fledged features don't appear out of thin air - they need strategy, communication, roadmap, tickets, prioritization and so forth. Interestingly enough, most features of Design Systems won't be finalized, but rather consistently grow in size and complexity over time.

Benefits of a Design System

If you are here and almost bored, jump to the next section NOW.

Seriously, it's the most cliche part of the essay. It's so corny that we should change the heading immediately. Here goes nothing!

- Benefits of a Design System

+ The Bestestest part of a Design System

While some advantages of Design System installation might be immediately noticeable and appreciated by the stakeholders, others might not be so evident. In various sources you might find more aspects, however usually they would stem from one or another more prominent points.

Top 2:

Consistency: Ensuring a uniform visual and UX across UI.

Efficiency: Saving time and thereby, financial resources, in development.

Runner-ups:

Accessibility: Integrating and fostering best practices from the jump.

Scalability: A problem solver for scaling issues across various platforms.

Practically speaking, this is what Design Systems were created for in the first place. Ironically, it's often taking second place now...

Faster Rebranding and Refactoring: Making large-scale updates breezier.

Beyond the obvious:

Faster Onboarding: Streamlining the integration process for development and design.

Recruitment: Positioning the organization attractively for top-tier talent.

Finally, there's a gimmick often named a "Common Language" for an organization. Commonly, it's the poetic interpretation of the fact that teams strive for or have achieved effective collaboration and streamlined their production processes, not without the help of a well-established Design System. Should we put it in a separate category? Sure, just remember to explain what is meant by that during a pitch. Instead of "hmm" you may count on "ohh!".

Design System Caveats

Well, here's the main reason why this very article was hatched in the first place. Honestly, I expected more content for this section, however, previous chapters already provide quite an extensive problematic coverage - in case you skipped it, consider going back. Remember this statement, it’s a blunt solution for the caveat number N, so we'll see it in detail further.

Investment

Establishing a Design System demands both time and financial investment. This upfront cost, which requires management buy-in at company and project levels, predicates a future return on investment through eventual time and cost efficiencies.

Cost-Effectiveness

A Design System is fundamentally crafted for scalability, posing itself as a service particularly beneficial to multiple projects. While it can certainly manage the UI for a singular project, its cost-effectiveness truly shines when deployed across numerous ventures.

Longevity

Longevity is intrinsic to a Design System’s makeup, operating as a perpetually tuned and smoothly functioning entity. Should any of its fundamental pillars - deliverables, maintainers, or processes - become obstructed, it risks transforming into a barrier itself.

Creativity Gateway

The Design System can intentionally or inadvertently become an operated valve for creativity, often a focal point for critique. Nevertheless, in contemporary organizations, the potential stifling of creativity is typically mitigated in advance through strategic training and process establishment.

System Errors

Like all systems, a Design System is not immune to architectural pitfalls. Common missteps include initiating numerous competing projects instead of starting small and failing to plan for long-term maintenance. Both provide a misleading sense of initial control but tend to manifest as obstructions in the long term.

That's worth a short digress.

What's a long-term vs short-term anyway? Let's put it on a virtual timeline. Roughly put, it's a threshold of 1 year or so. Usually, foundations should be established after 1 year of development, and then the real work begins.

Design Systems are somewhat slow, multi-staged (also -layered and -faceted) projects, where each stage would be unique in aspects of length, growth, issues, requests, processes, maintenance effort and so on. Planning only for growth and overlooking long-term support is as dangerous as starting with all features and conflicting priorities, eventually making foundation establishment a never-ending resource-guzzler. Both examples relate to architecture and can be called system errors of Design System development. That's an oxymoron I would shy away from.

It’s a wrap!

Creating and maintaining a Design System is naturally full of challenges. I reckon we should be more transparent and candid about possible roadblocks and considerations. Getting buy-in from stakeholders is one thing, return on investment is another.

Design Systems have been generously contributing to the realm of consistency and efficiency in the digital development terrain since 2015 or so, marking not merely a trend but an industry staple. Naturally, as we navigate the evolution of technology and design, the exploration, critique, and refinement of Design Systems forge ahead, too!

This article is an interim stage where I take a chance to analyze personal and collective experiences with Design Systems, as that needs to happen from time to time. I also hope that it will encourage us to revisit how Design Systems contribute to our digital environments now and anticipate next-gen challenges and innovations with an open yet slightly more rational mind.

❤️ Thank you for reading!

Get in touch on LinkedIn!

Swift theming and design system foundation with Design Tokens Generator

Evgeny Khoroshilov — Fri, 02 Jun 2023 16:30:00 +0000

Design Tokens Generator is a powerful tool that aims to simplify the management of design tokens for designers and web developers.

The goal of the app is to make design tokens more approachable and user-friendly. With Design Tokens Generator 👑😈🎨👽, you can focus on your creative vision while the app takes care of the tedious aspects of design token taxonomy. It provides a streamlined solution for managing design tokens, allowing you to effortlessly establish a strong foundation for your Web Project, App or Design System.

Design Tokens Generator offers an intuitive interface and user-friendly features to streamline the process of working with design tokens and achieve greater design consistency and scalability in projects faster.

Design Tokens in a Nutshell

Design tokens have revolutionized the way we approach design systems. These platform-agnostic design values serve as the sub-atomic units of a design language (see illustration below), ensuring consistency and coherence across various platforms and projects. Design tokens also enable the creation of a cohesive and harmonious design language. By establishing standardized values for colors, typography, spacing, and other design elements, a consistent visual identity is maintained.

By defining design attributes as tokens, updates or changes can be easily applied and propagated throughout the system. This eliminates the need for manual updates across multiple instances, saving time and effort while ensuring consistency. A single modification to a design token can have a cascading effect, harmonizing the design elements across the entire project. In a nutshell, it is the concept of design tokens as the foundation for a design system.

Leveraging the benefits of design tokens, teams can streamline their design processes, enhance collaboration between designers and developers, create more efficient design systems and deliver exceptional user experiences.

The Problem with Design Tokens no one talks about

While design tokens are a simple and powerful concept in theory, their practical implementation can often become daunting and complex. What initially seems like a straightforward solution for maintaining design consistency across projects can quickly turn into a roadblock.

With design tokens teams face the issue of finding the right balance between generality and specificity. Existing open-source solutions often fall into two extremes. On one hand, there are prominent and generic solutions that aim to cover a wide range of use cases. While these solutions may be suitable for larger projects, they can be overwhelming and impractical for smaller-scale projects. On the other hand, there are specific solutions that originate from other team projects. While these may address certain unique requirements, they lack the flexibility needed for customization and adaptation.

In both scenarios, without a proper framework or tool, managing and adjusting design tokens can become a taxonomy nightmare, hindering maintainability and scalability. Struggle with organization, support, and maintenance of their design tokens hampers productivity and can lead to inconsistencies across projects.

In the next section, we’ll get to know the Design Tokens Generator, a solution specifically designed to address these challenges and make working with design tokens more approachable and intuitive.

Introducing the Design Tokens Generator

The Design Tokens Generator was developed as an approachable solution to bridge the gap between the simplicity of design tokens and their practical implementation.

It offers a streamlined and intuitive experience for designers and web developers, making design tokens more user-friendly and manageable. The app also strives to simplify the customization of design tokens, empowering you to create and adjust tokens with ease while ensuring consistency and scalability across your projects.

Key Features

Streamlined Design Tokens Naming Model: The app offers an opinionated, simplified and intuitive naming model for design tokens. It allows for easier memorization and organization of tokens, enhancing the efficiency of tokens management.
Sufficient and Effective Tokens for Small- and Mid-Scale Projects: The Design Tokens Generator provides a curated assembly of design tokens that are suitable for small- to mid-scale projects. It eliminates the complexity of dealing with an overwhelming number of tokens, ensuring that you have the necessary tokens without unnecessary clutter.
Intuitive UI for Customization: The app features an intuitive user interface that allows you to customize design tokens according to your project requirements. You can easily adjust prefixes, typescale, color palette, unit formats, and more, enabling you to create a design system that aligns with your unique needs.
Live Interactive Preview Area: The Design Tokens Generator includes a live preview area where you can instantly visualize the adjusted tokens. This allows you to see the impact of your customization in real-time, making it easier to fine-tune and iterate on your design system.
Export to Popular Formats: The app enables you to export your design tokens to popular formats, with CSS variables as the foundation. This makes it effortless to integrate the generated tokens into your frontend codebase and ensure consistency across different platforms.

Now let’s dive deeper into the practical side of Design Tokens Generator. In the following section, we will explore how design tokens are organized within the Sets and Collections. By understanding these concepts and interface controls, you will gain a deeper understanding of how to harness the power of design tokens for your projects.

Collections, Sets and their Purpose

The Design Tokens Generator is organized in a straightforward and intuitive manner. The app groups design tokens into compact clusters known as Sets. These Sets are then combined into larger groups called Collections.

There are five Collections in the App, each based on design domain principles. Each Collection comprises one or more Sets, providing a robust and complete set of design tokens.

To understand the contents of the Collections, a quick glance at the Design Tokens Generator logo from both sides is sufficient:

Each Collection here is represented by a distinct icon or emoji. These Collections serve as the foundation for organizing and managing your design tokens, revolving around a Core element that drives consistency and coherence throughout a project.

Colors — Palette (🎨) Naturally, the Palette icon represents the extensive Colors Collection. This collection allows you to define and harmonize your color palette, creating a visually appealing and cohesive experience.
Content — Crown (👑) The Crown icon embodies the Content Collection. It focuses on typography and text visualization, ensuring a regal prominence for your textual elements.
Space and Dimension — Alien (👽) The Alien icon signifies the Space and Dimension Collection. Space and dimension (along with sizes) are combined for a generalized approach. This simplifies the management and organization of these design aspects.
Details — Devil (😈) The Devil icon personifies the Details Collection. This collection adds that extra touch, injecting personality and flair into your visual language.
Generic Properties — Cog (⚙️) Lastly, the centerpiece Cog icon represents the collection of Generic Properties (the Core Collection). These properties may not be design-specific or limited to mobile app development but play a fundamental role in shaping your project, such as defining the root-size.

Now, let’s dive deeper into each Collection and explore the unique Sets they contain. These Collections have been thoughtfully organized to cover various aspects of your design system.

Palette Collection (🎨)

As mentioned earlier, the Palette Collection contains the most Sets and tokens. Here’s a brief overview of the Sets within this Collection:

Brand colors: Primary, Secondary, and Accent color Sets representing a brand’s main color scheme.
Util colors: Safe, Alert, Info, and Warning color Sets for elements like loading indicators, error messages, and notifications.
Foundation colors: Gamma, Base, and Contrast color Sets. Gamma offers a range of shades, while Base and Contrast define background and content colors for high contrast and accessibility.
Text colors: A standalone Text Set with regular, strong, subtle, and accent variations.

Let’s take a closer look at the structure of a color Set (excluding Foundation colors). Each Set consists of the following values: base, contrast, tint, shade, and tone. The lead color (Primary #3675e8 in this example) is tweakable, and other values are calculated automatically.

contrast: the color that provides sufficient contrast to the base color (values are inherited from the Gamma Set)
tint: a brighter and more intense variation of the base color
shade: a darker and less vibrant variation of the base color
tone: a mixture of the base color with a neutral gray

For Gamma, you can also define the lead color and adjust the gamma progression control:

Text colors have regular, strong, subtle, and accent variations, with the option to switch or invert them depending on your primary theme. Experimenting with the Gamma and Text settings can help achieve the desired result for your project.

To explore the Palette Collection further please refer to the guide.

Content Collection (👑)

The Content Collection focuses on three essential Sets: Font Size, Line Height, and Icon Size.

Font Size and Icon Size Sets share similar naming conventions and settings options. The tokens in these Sets follow a “t-shirt” naming approach, ranging from xs to xxl, with a default base n value of 1rem (16px). The values for other tokens are calculated based on the chosen scale setting, which determines the progression of the tokens.

Scale options represent multipliers that build upon the previous value, allowing for distinct or subtle differences in size. Practically this control uses the type scale generation principles, allowing to have a quick all-in-one solution within the app.

The Line Height Set, on the other hand, is controlled slightly differently due to the nature of this property. It typically requires fewer values. The tokens in this Set include regular, tight, and loose, representing different line spacing options.

In summary, the Content Collection provides you with the tools to control the sizes of fonts, line heights, and icons in your design system. To explore the Content Collection further please refer to the guide.

Space Collection (👽)

The Space Collection in the Design Tokens Generator consists of two sets: the main Set — Spacing and the auxiliary Set — Local.

The Spacing Set provides a range of spacing tokens, named with a numeric convention such as space-075, space-100, space-125, and so on. The base token, space-100, serves as the reference point, and other values are derived from it using a progression factor. This approach offers a practical and intuitive way to work with spacing, allowing you to easily calculate and adjust values based on the base token.

The progression of the spacing scale is (almost) linear, unlike the typography generation style. It follows the design principle of using a standard grid with 2 or 4-pixel increments, which simplifies offset setups and ensures easy maintenance.

However, if you need specific measurements that don’t align with the scale, you can calculate them on the spot using the base token (space-100) and multiplying it by the desired factor.

The Local Set within the Space Collection introduces specific pattern-like tokens that are particularly useful in web and mobile app development. These tokens can be customized and experimented with to meet the specific needs of your project. In addition to the predefined tokens, you also have the flexibility to add custom spacing tokens based on specific use cases. Naming them according to their purpose enhances their association with particular patterns in your project.

Welcome to further explore the Space Collection in the guide document.

Details Collection (😈) aka “the Det😈ils”

It’s getting hotter and more exciting!

Details play a crucial role in enhancing the user experience. While too many details can be overwhelming, carefully chosen details can elevate the overall design. The Sets in the Details Collection are diverse and not directly related to each other, but they can inherit color and spacing values from other Sets within the design system.

Radius: This Set focuses on defining the radii of elements. It includes tokens for standard values like small, medium, and large, as well as auxiliary tokens like round and pill, which determine the shape of the element.

Shadow: The Shadow Set offers natural-looking shadow tokens along with the tint color. Tokens are named small, medium, and large for consistent usage. The tint color can be adjusted based on the design requirements of your project. Typically, it is derived from black or dark shades of gray, however you may need to adapt the tint color to ensure a more cohesive and natural appearance.

Duration: The Duration Set consists of tokens that control transitions and animations in your application and implement the time concept. The available tokens include instant, short, regular, long, and extra values. When selecting a base value and scale for timing tokens, consider that the duration of transitions should be proportionate to the size of the element. Larger elements generally require longer transitions, while smaller elements benefit from shorter and more responsive animations.

Finally, the Selection Set enables you to control the colors for content selection in your project. While often overlooked, customizing the selection colors can easily add an individual touch to the overall design.

Welcome to explore the Details Collection on a dedicated page.

Core Collection (⚙️)

The Core Collection is composed of a single Set that contains a crucial token for global control over the scale of your application. This token is named root-size and represents the font-size value that can be applied to the root element, typically the html tag in web projects. By default, the root font size is set to 16px in most modern browsers.

The root-size token can be utilized in calculations for relative values. For instance:

html {
 font-size: var(--awsm-root-size);
}

@media (min-width: 1200px) {
 html {
   font-size: calc(1.25 * var(--awsm-root-size));
 }
}

In this example, the font-size of the root element is set to the value of --awsm-root-size, and for viewport widths larger than 1200px, it is increased by a scale factor of 1.25.

Using the rem unit in conjunction with the root-size token ensures a consistent visual style for your application, irrespective of the device resolution or rendering medium. It also helps maintain accessibility compliance when users zoom in or out. By controlling the root-size token, you can establish a consistent and responsive typography system across your entire application.

Flexibility and Control

Each tokens Set consistently bears the minimum amount of similar controls, specifically the Prefix editor and Toggle control, allowing for more flexible organization of your design tokens output.

Prefix editor allows you to modify the prefix for the Set. When you change the prefix, all related tokens that use the current tokens as aliases will be updated in real time.

Toggle control allows you to include or exclude the current Set from the final output. By default, the Set is included in the output. Note, that the Preview area will always visualize all token values regardless of the toggle state.

If we “zoom out” to the global scope of the app, we’ll find the Global Prefix editor in the central area of the Header. This control allows you to customize the overall assembly of design tokens according to your specific project requirements. Global prefixes are commonly used in UI libraries and design systems to prevent variable clashes and accidental overrides. They also make it easier to distinguish between custom and inherited tokens in your codebase.

Another global feature of Design Tokens Generator is the Auto-save functionality. It’s convenient when you need to take a break between design sessions and ensure consistency of your changes. Additionally app allows to quickly reset all customizations to the original state.

It’s worth noting that saved changes are local to your browser and may be reset if you clear your browser data. The app strives to preserve your data, but depending on the complexity of updates and release changes, there may be cases where everything is reset. Therefore, it’s recommended to save your work externally to ensure its safety.

Those and other useful controls can be further explored in the official guide.

Wrapping Up

I hope that Design Tokens Generator 👑😈🎨👽 can be used with fun and practicality to your everyday work. The aim is to provide you with a tool that enhances your creative process and makes your projects more enjoyable to develop.

My primary focus with this App is to make design tokens and design system establishment more approachable for small- and mid-scale projects, regardless of team size and expertise. It can be a perfect companion for the Design, Frontend, Full-stack and Product management needs in Web and App development areas.

Your feedback is valuable and welcome. If you have any suggestions for improvement, feature requests, or general feedback, please reach out.

Also feel free to reach out to me for collaboration opportunities or to share your thoughts on how the app can be further enhanced to meet your needs. Please refer for more information to the About page.

Bookmark Design Tokens Generator and stay tuned for new releases, updates and useful tutorials!

And of course, your support is very much appreciated!

Check out the ProductHunt page for more information.

Welcome to spread the word about Design Tokens Generator via Twitter, Facebook and other networks.