Engineers hate tech debt. At every CTO, VP, or director Q&A I've attended, an IC asks about how much time will be dedicated to paying it down in the next quarter or year. The answer is always unsatisfactory.

The unspoken reason tech debt payments are so hard to get sign-off on is clear[^1]: they provide little quantifiable value to the business. From the top-down, playing it safe is preferred.

[^1]: When you're at a large firm it always feels good to hear an exec admit the writing is on the wall. Candor is common where I work right now, but there is always something that is not being said.

1. An initial solution is developed
2. Feature creep from building $n + 1$ takes place
3. A refactor takes place to abstract or generalize the solution
4. Repeat steps 2-3 for the life of the project

This cycle is inherent in creating any system. What matters is how long the cycle lasts. Keeping this cycle too short or too long is expensive:

• Too long --> technical debt
• Too short --> overfitting

I find that the technical debt problem is well understood and the overfitting problem, exacerbated by avoidable refactors, is not.

Overfitting

You can think of refactors like database or Django migrations. Refactors are a way to keep the codebase in sync with business problems. The longer you wait to do them, the more of a headache they become, but a large, superfluous migration can be dangerously expensive.

A refactor is a functionally equivalent solution that incorporates '$n+1$' features into a new solution that treats all features as first-class citizens, where $n$ is all features added before the last refactor or architecture plan.

This leads to a new set of problems. Each time new features are added to the solution, the scope must be broadened. The more you try to generalize, the more you overfit[^2]. The more you overfit, the more you have to refactor.

It follows that unnecessary refactors lead to unnecessary overfitting. It's important to avoid refactoring as the new guy or overzealous engineer.

[^2]: I'm borrowing the term 'overfitting' from the problem in machine learning. It occurs when a model is trained to fit a specific set of data too closely. As a result, the model will perform well on the training data, but poorly on new data in the field.

Basic Real-World Example

Traffic systems are a hard problem. This example is oversimplified. Say we had a traffic control system that handled a single intersection. We might start with a simple solution involving a single traffic light. Soon we will realize that we need to handle multiple lanes of traffic. We might refactor to a solution that handles multiple lights. In the revised solution, the number of lanes and their attributes are codified.

Over time, our model of the problem becomes more complex. We need to handle multiple intersections, pedestrians, and transit lanes. We might refactor into a solution that handles all of these things. Construction costs money and time, so we want to minimize rebuilding and weak optimizations.

This example is fairly contrived, but its principles fit any system with flow and constraints.

Back to Software

In software, product needs are much more fluid than roads and infrastructure; this cycle occurs a lot faster[^3]. Any ground-up refactor will accomplish incorporating new features in a way that feels elegant to the solution, but it's a local maximum with consequences.

[^3]: It's not difficult to iterate faster than public works in most industries. It seems like every exciting BART or Caltrain plan is always years out of reach.

Taking this idea to its limits, the only way to avoid refactors is to have perfect foresight. Often, this is realized as a domain-specific language (DSL) that is expressive enough to handle all the features that will be added in the future[^4]. In implementation, a system robust enough to handle any programmable business need would approximate a programming language. Getting just the right amount of abstraction is always difficult and requires great judgment.

[^4]: DSLs are great, but not a silver bullet. The reason migrations exist in the first place is an acknowledgement that a problem is too complex to be solved in one go.

Refactors are reflective only of current and known needs. Modeling real world problems is hard, but complete rewrites lead to premature optimization and overfitting to the current problem set. There is a tendency to refine a working solution to the point of diminishing returns.

By refactoring too early, you are creating too rigid a solution. The framework that solves the current feature set will inevitably be too narrow for the next one.

1. To build a solution to a problem
2. To use a new technology

I have also found that these two goals are often at odds with each other. When I want to learn a new technology, I am trying to learn a new way of thinking about problems. It's difficult to implement basic product needs when you're figuring out how to handle sorting a list in a new language.

Trying new things is important. There was a time 10 years ago when everybody's JavaScript looked different. Now we have many great ways to write JavaScript. Whether you prefer functional patterns or dependency injection and OOP, the tooling around those conventions borrows from other languages.

Neither of these motivations is misplaced. But it's difficult to keep track of both how the system maps to the business problem and how the technology maps to the system. Tackling more problems that are novel to you increases the surface area of the problem, while your capacity to solve it remains the same.

Most people are most effective at learning one thing at a time. It follows that the reason a lot of programmers don't finish side projects is because they're trying to learn too much at once. It's easy to get greedy and try to kill two birds with one stone. Similar to how there is always a higher priority, there is always something new to learn.

I approach side projects more effectively by applying as many constraints as possible and being intentional about one goal. Like all good work, focus is required.

When learning a new technology, I'll default to an app I've built before. Some examples include a Socket-based chat app, a simple CMS, or a cloud-backed Todo app[^1]. The product problem is narrow. These apps have a low ceiling[^2] but also a low floor, making them great for learning.

[^1]: Building systems that have some user-facing and data-fetching components are great since they force you to use practical async code. [^2]: I don't mean to say that these apps cannot be executed well. Honk proved otherwise.

If I am trying to build a product or write software to solve a problem, then design and product are where my energy goes.

You want to use a stack as boring as possible--a stack with no big 'if's. If you're most comfortable with NoSQL than SQL, then use it. It should be intuitive for you to prototype, teardown, rebuild, and deploy. Minimize twists and turns.

No advice is grossly generalizable. I've met people who love to struggle through problems and hold a lot of context at once. This probably isn't true for most people. There's a reason companies use boring stacks. But if you know yourself better than I do (which is likely), then you should do whatever gets you to output great things. Being honest with yourself goes a long way.

[^1]: There is also a productivity boost, even without this context loss. I am usually developing my own designs, but even with Framer Motion, I just find it easier to iterate on flows and interactions with prototyping animations in Figma.

Figma's "smart animate" mode is particularly useful for prototyping animations. It essentially generates a tween[^2] between two artboards based on the position and size of the layers in each frame. Sometimes results are surprisingly good. While it tends to perform pretty poorly on complex animations, it's great for simple interactions that do add polish to a design.

[^2]: A tween is a type of animation that interpolates between two states. For example, a tween between two artboards might move a layer from one position to another. Read more on Wikipedia.

Embedding Figma Prototypes

Figma prototypes can be shared via a link, but it's also possible to embed them in a webpage. It's awesome for quick demos within a website or blog post without writing a lot of one-off code. MDX makes it even easier to embed Figma prototypes in a blog post.

There's no great off-the-shelf solution for styling the embed, but Figma provides a couple options to hide their baked-in UI and iframe-ing in the prototype itself.

This is how an embed from Figma looks by default:

<iframe
  style="border: none;"
  width="800"
  height="450"
  src="https://www.figma.com/embed?embed_host=share&url=https://www.figma.com/proto/..."
></iframe>

Already, there are a few annoying things about this embed:

• The iframe is not responsive
• The Figma embed UI is too busy over the prototype

Prop API

If we're embedding a lot of prototypes, it's nice to have a reusable component that handles these issues. I wanted this component to:

1. Be responsive to the container width
2. Bring my own UI for metadata and controls
3. Link to the original Figma file

Given the constraints, here's the API I came up with:

type FigmaEmbedProps = {
  url: string;
  aspectRatio: number;
};

I'll admit that having to provide an aspect ratio is pretty awkward, but it's the only way to make the embed responsive. The content is not only cross-origin but rendered on a canvas inside of Figma's app code, so aspect ratio inference is not possible.

Given the aspect ratio, we can calculate the height of the embed based on the width of the container.

As for getting a link to the Figma file, we can parse the url parameter to extract the file id and construct a link to the editor page.

function FigmaEmbed({ url, aspectRatio }: FigmaEmbedProps) {
  if (!url.includes("hideUI")) {
    // if the url is unopionated about hiding
    // the Figma UI, then hide it
    url += "%26hide-ui%3D1";
  }

  return (
    <div
      style={{
        position: "relative",
        height: "auto",
        aspectRatio,
      }}
    >
      <iframe
        style={{
          width: "100%",
          height: "100%",
          border: "none",
        }}
        // forward provided embed url
        src={url}
        loading="lazy"
      />
    </div>
  );
}

import { FigmaLogo } from "icon-library"; // not a real package

/**
 * Extract the file id from a Figma prototype url
 */
function extractFileURL(url: string) {
  const regex = /proto%2F(.*?)%2F/;

  const match = url.match(regex);
  const id = match?.[1];

  return id;
}

function FigmaEmbed({ url, aspectRatio }: FigmaEmbedProps) {
  const fileId = extractFileURL(url);

  if (!url.includes("hideUI")) {
    // if the url doesn't is unopionated about
    // hiding the Figma UI, then hide it
    url += "%26hide-ui%3D1";
  }

  return (
    <div className="figma-embed">
      {fileId && (
        <a href={file} target="_blank">
          <FigmaLogo />
          Open in Figma
        </a>
      )}
      <iframe src={url} loading="lazy" />
    </div>
  );
}

Designing Overlays

I wanted to create a floating link to the Figma file and have it positioned over the prototype itself. This link needs to always be readable, and we don't know what the background of the embed's artboard will be until runtime.

There are a few solutions to this problem, but I decided to use CSS mix-blend-mode and background-blend-mode to maintain contrast. Most of the time the link will be over a pure color, so difference and darken work well to provide basic readability and a background for a hover state.

.figma-embed {
  position: relative;

  /* ... */

  a {
    position: absolute;
    top: 16px;
    left: 16px;
    z-index: 1;

    mix-blend-mode: difference;
    background-blend-mode: darken;

    color: white;
    background: transparent;

    &:hover {
      background: #121313;
    }
  }
}

Putting it all together

Here's the final React component made to fit with the rest of this site:

<Figma url="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Fproto%2FwbMsekj41OFW9sCkpPRd58%2FEmbedded-Figma-Prototypes%3Ftype%3Ddesign%26node-id%3D97-574%26t%3DKQ20KtCCGbjzNyzL-1%26scaling%3Dmin-zoom%26page-id%3D95%253A549%26mode%3Ddesign" aspectRatio={4 / 3} />

export type Intent =
  | "default"
  | "muted" // e.g. a grey button
  | "success"
  | "danger"
  | "warning";

The concept of intent is ingrained in nearly every design system. For example, in MUI, a button has a color prop (in MUI, color tokens are defined by their intent). These parts of the system work together like this: <Button color="danger">Delete</Button>.

UI libaries like Blueprint and Evergreen use the name intent for this prop.

I prefer calling this prop intent instead of color because it is more to the point. An intent prop can be used for more than just buttons; it can be applied to notifications, banners, results, and various other components.

The MUI method of using colors named for their intent is a bit cumbersome, but allows for an escape hatch for when specific colors are needed. The use of intent as a prop works great in tandem with utility props like those that styled-system introduced.

It is a great abstraction since its implementation lies at the component layer. This provides enough flexibility to create a design language that is consistent while also being narrowable for product needs.

This might sound like a nitpick—what's in a name[^1]? But I think it's important to have an accurate name for such a keystone concept. While software design communicates with users, a design system communicates with one's peer implementing @company/ui in their product. Intent seems like the best way to create a unified API across the entire system for this purpose.

[^1]: From a code perspective, I was so satisfied when I came across the name 'intent' when studying Segment's Evergreen design system. I had been bouncing between color and type, both of which caused collisions with other props.

<Notification.Tray>
  <Notification.Item intent="success">
    Your changes have been saved
  </Notification.Item>
  <Notification.Item intent="warning">
    Your session will expire in 2 minutes
  </Notification.Item>
  <Notification.Item>
    Consider saving your changes with &#8984; + S
  </Notification.Item>
</Notification.Tray>

Getting the last updated date

Contentlayer document types give us reference to the raw source file, which we can use to get the last modified date using Node functions.

import fs from "node:fs";
import path from "node:path";

import { DocumentGen } from "contentlayer/core";

/**
 * Check when a contentlayer document's source
 * file was last updated
 */
export function getLastEditedDate(doc: DocumentGen): Date {
  const filepath = path.join("posts/", doc._raw.sourceFilePath);
  const stats = fs.statSync(filepath);
  return stats.mtime;
}

Defining a computed field

This helper can be used to define a lastEdited field on the Post document type which will resolve at build time.

import { getLastEditedDate } from "../utils";
import { defineDocumentType } from "contentlayer/source-files";

export const Post = defineDocumentType(() => ({
  name: "Post",
  contentType: "mdx",
  filePathPattern: `**/*.mdx`,
  fields: {
    title: { type: "string", required: true },
    date: { type: "date", required: true },
  },
  computedFields: {
    lastEdited: {
      type: "date",
      resolve: getLastEditedDate,
    },
  },
}));

Using the lastEdited field

After generating types again the lastEdited field is available on the Post type and can be rendered on posts. The field is a Date object, so it can be formatted using a library like date-fns.

import { Post, allPosts } from "contentlayer/generated";
import { useMDXComponent } from "next-contentlayer/hooks";
import { format } from "date-fns";

export default function Post({ post }: { post: Post }) {
  const MDXContent = useMDXComponent(post.body.code);

  return (
    <article>
      <h1>{post.title}</h1>
      <MDXContent />
      <footer>
        Last updated
        <time dateTime={post.lastEdited}>
          {format(post.lastEdited, "LLLL d, yyyy")}
        </time>)
      </footer>
    </article>
  );
}

CSS variables:

1. Are scoped the an element and it's children
2. Work with the calc() function
3. Can be changed at runtime

Theming

import styled from "@emotion/styled";
import { variant } from "styled-system";
import * as Menu from "@radix-ui/react-menu";

const MenuItem = styled(Menu.Item)`
  background: var(--background);
  color: var(--color);

  ${({ theme }) =>
    variant({
      prop: "intent",
      variants: {
        "default:hover": {
          "--color": theme.colors.grey900,
          "--background": `${theme.colors.grey400}`,
        },
        "danger:hover": {
          "--color": theme.colors.red800,
          "--background": theme.colors.red100,
        },
      },
    })}
`;

export function Menu() {
  return (
    <Menu.Root>
      <Menu.Content>
        <MenuItem>View Details</MenuItem>
        <MenuItem>Add Record</MenuItem>
        <Menu.Separator />
        <MenuItem intent="danger">Delete</MenuItem>
      </Menu.Content>
    </Menu.Root>
  );
}

In the above example, we are using the variant function from styled-system to create a button component that can be themed. Note how we map theme colors, named for their color, to CSS variables named for their user-facing intent.

Responsive Design

For scalable designs (e.g. graphics made with code) we can use calculations with CSS variables to properly scale children up and down without having to manually calculate the values.

.card {
  &__wrapper {
    --card-padding: 1rem;

    padding: var(--card-padding);

    @media (min-width: 1200px) {
      --card-padding: 1.625rem;
    }

    @media (min-width: 720px) {
      --card-padding: 1.25rem;
    }
  }

  &__main {
    position: absolute;
    top: var(--card-padding);
    left: var(--card-padding);
    width: calc(100% - (var(--card-padding) * 2));
    height: calc(100% - (var(--card-padding) * 2));
  }
}

Contentlayer is a library that acts as like an ORM for markdown content. It has become popular in the Next.js ecosystem as a way to manage content for static sites. It's easy to build on top of since all content is available through a strongly-typed, generated module.

The allDocuments array can be iterated over to find all the documents that link to a given page. Here's a function that returns an array of backlinks for a given slug:

import { allDocuments } from "contentlayer/generated";

function getLinkedMentions(slug: string) {
  return (
    allDocuments
      // filter out documents that don't contain a link
      // to the provided document
      .filter((doc) => doc.body.raw.includes("[[" + slug))
      // map to title and slug for rendering
      .map((doc) => ({
        title: doc.title,
        url: doc.url,
      }))
  );
}

Usage

Then, in your page component, you can call this function and render the results. The example below is in Next.js, but the approach can be used broadly.

import { getLinkedMentions } from "@/lib/linked-mentions";

export default function Page({ slug }) {
  const mentions = getLinkedMentions(slug);
  return (
    <div>

      <!-- page content -->

      <h3>Mentions</h3>
      <ul>
        {mentions.map((link) => (
          <li>
            <a href={link.url}>{link.title}</a>
          </li>
        ))}
      </ul>
    </div>
  );
}

The pattern became popular thanks to Reach UI and, more recently, Radix Primitives. These libraries utilize this pattern to offer ready-to-use accessibility and behavior. However, they delegate styling and composition to the user.

import * as Tabs from "@radix-ui/react-tabs";

export default () => (
  <Tabs.Root>
    <Tabs.List>
      <Tabs.Trigger value="1">1</Tabs.Trigger>
      <Tabs.Trigger value="2">2</Tabs.Trigger>
    </Tabs.List>
    <Tabs.Content value="1">Tab 1 contents</Tabs.Content>
    <Tabs.Content value="2">Tab 2 contents</Tabs.Content>
  </Tabs.Root>
);

Users can define their own markup using this API. The parent component, controlled by the library developer, can still manage state and behavior.

If you want to read more about compound components, I recommend this article by Kent C. Dodds.

This remainder of this post contains some guidelines I've come up with for creating compound components after both consuming and implementing them.

Designing defensive slots

In the compound pattern, slots are represented as children of sub-components as opposed to props. React understands children as an array of ReactNode regardless of the use case, so it's important to design your slots defensively.

Ensure there is only one child

If there should only be one child, use React.Children.only to ensure that there is only one child. This will throw an error if there is more than one child.

This is useful for slots that should only have one child. Common examples are icon wrappers like <Button.Append>, <Input.Prepend>, or <Input.Icon>.

const iconWrapperCSS = css`
  width: 2em;
  height: 2em;
  display: flex;
  align-items: center;
  justify-content: center;

  svg {
    width: 1.5em;
    height: 1.5em;
  }
`;

const IconWrapper = ({ children }) => {
  const { toggleMenu } = useMenuContext();

  // assert that there is only one child
  const child = React.Children.only(children);

  return (
    <div css={iconWrapperCSS}>
      {React.cloneElement(child, {
        onClick: () => toggleMenu(),
      })}
    </div>
  );
};

Apply Props to Children

React.cloneElement

If you need to add props to children, use React.cloneElement to add props to children. This is useful for slots that need to pass props, such as listeners, to a child.

Radix establishes the convention of using the asChild prop to indicate that the child should be cloned. Without this prop, the children are rendered into the default element (e.g., a button for a trigger).

const AccordionTrigger = ({ children, asChild }) => {
  const [isOpen, toggleOpen] = useReducer((open) => !open, false);

  if (asChild) {
    // assert that there is only one child
    const child = React.Children.only(children);

    // clone the child with listener and state
    return React.cloneElement(child, {
      onClick: toggleOpen,
      "aria-expanded": isOpen,
    });
  }

  return <button onClick={toggleOpen}>{children}</button>;
};

React.Children.map

Use React.Children.map with React.cloneElement when iterating over children. This allows you to add props to the children.

const Tabs = ({ children }) => {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      {React.Children.map(children, (child, index) => {
        if (React.isValidElement(child)) {
          return React.cloneElement(child, {
            "data-active": index === activeTab,
            onClick: () => setActiveTab(index),
          });
        }
      })}
    </div>
  );
};

API Design

Export Structure

Compound components allow users to import from a single namespace for convenience. Sometimes, users may want to import a single component separately. They can do this to optimize for tree-shaking or to avoid naming collisions. For this reason, it's important to export both un-prefixed and prefixed components.

import { Root } from "./components/root";
import { Item } from "./components/item";
import { Trigger } from "./components/trigger";
import { Content } from "./components/content";

export {
  // un-prefixed exports for namespacing
  Root,
  Item,
  Trigger,
  Content,

  // exports for prefixed, non-namespaced imports
  MenuRoot,
  MenuItem,
  MenuTrigger,
  MenuContent,
};

Styling States

Compound components are often used for components that have multiple states. For example, a menu can be open or closed. A tab can be active or inactive. A switch can be on or off.

When providing a component that has multiple states, it's important to provide a way to style each state. Accessible components should use ARIA attributes to indicate state, but these do not provide enough coverage and can be unintuitive as selectors.

For example, a menu can be open or closed. The aria-expanded attribute is used to indicate this state. While workable, a declarative set of data-* attributes allows for a more user-focused API.

const Tabs = ({ children }) => {
  const [activeTab, setActiveTab] = useState(0);

  return (
    <div>
      {React.Children.map(children, (child, index) => {
        if (React.isValidElement(child)) {
          return React.cloneElement(child, {
            // add data-active attribute to indicate state
            "data-active": index === activeTab,
            onClick: () => setActiveTab(index),
          });
        }
      })}
    </div>
  );
};

Then the active tab case can be styled like so:

[data-active="true"] {
  background: var(--color-primary);
  color: var(--color-white);
}

Controlled Components

Complex or multi-step interfaces, like forms, demand inversion of control. In other words, the parent component should control the state of the child. A rich API should allow for controlled components as an opt-in.

This can be done by accepting a prop to use as state and defaulting to internal state when the prop is not defined. Additionally, a callback for updates (e.g., selecting a tab) should be provided by the user.

type TabControlledProps = {
  current: number;
  setCurrent: (index: number) => void;
};

type TabsProps = Partial<TabControlledProps> & PropsWithChildren;

const Tabs = (props: TabProps) => {
  const [currentTab, setCurrentTab] = useState(0);
  const { current: controlledCurrent } = props;

  // if the current prop is defined, use it as the state
  const activeTab = controlledCurrent ?? currentTab;
  // if the current prop is defined, use the provided callback to update it
  const setActiveTab = controlledCurrent ? props.setCurrent : setCurrentTab;

  return (
    <div>
      {React.Children.map(props.children, (child, index) => {
        if (React.isValidElement(child)) {
          return React.cloneElement(child, {
            // use calculated state
            "data-active": index === activeTab,
            onClick: () => setActiveTab(index),
          });
        }
      })}
    </div>
  );
};

This site is more personal expression than a software product. Personal websites of mine have been forked and copied before, which is fine. However, I no longer want others using my site as a template. Josh W Comeau has a great write-up on this topic. I'd be reiterating a lot of what he said if I continued here.

Below is some general information on how this site was built. If you have any questions about the implementation, feel free to contact me on Twitter.

| Using | | | ------------- | ---------------------------------------------------------------------------------------------------- | | Rendering | Next.js, Content Layer, MDX | | Styling | Emotion, SCSS, XStyled | | Type | Inter, JetBrains Mono | | Hosting | Vercel |

Communication needs to be reliable. Users will always default to established platforms for sharing anything critical. Another chatbox, notification bell, or comment thread is not always appreciated. It is easy for new applications to become "another thing" to check.

Everything important happens on Slack, Teams, meeting notes, email, or whatever the team's preferred ritual is. If you need to be a part of that, you need to make it easy to share content from your application.

Sharing is a feature

If you are building a product that houses content, said content should be easy to share.

Printability

Say you are building office applications. Users often default to printing a page as a PDF to share content over email when they are unsure of the recipient's ability to open the file; a common pattern for sharing content cross-platforms.

It might be tempting to build a bespoke print or PDF export feature, but there is undoubtedly a more efficient use of your time. There is nothing wrong with using the browser's built-in print dialog: it is well-established and reliable.

Not all pages, especially, single-page applications with complex layouts are suitable to print out of the gate. In this case we can use the CSS @media print rule to create a print-friendly version of the page.

@media print {
  .document {
    /* remove dark-mode styles */
    color: black !important;
    background: none !important;
  }

  .toolbar,
  .cursor,
  .suggestion {
    /* hide elements that don't make sense to print */
    display: none;
  }
}

Some interfaces (like Google Sheets) completely override the browser print dialog in favor of a more feature-rich version. This is a great way to add polish to your product, but it can also be a much larger undertaking than ensuring the page is print-friendly out of the box.

In Google's case it makes sense to provide a custom UI since spreadsheets are complex and do not have an intuitive print layout. For getting off the ground with most applications this would be overkill.

Open Graph

Most people who work on websites or sell anything digital (i.e. SEO farmers) should be familiar with open graph (OG) tags. If you don't: they are data a website can provide to social media platforms to customize the images and preview text on a card.

{/* */}

Open graph data is used to generate a preview card when a link is shared in Slack. It's important for teammates to know what they're clicking at a glance.

APIs & Resources

• Clipboard API - A browser API for reading and writing to the clipboard.
• Open Graph Protocol - A standard for sharing content on social media.
• Web Share API - A browser API for sharing content to native apps.

The solution I was looking for entailed:

1. No JavaScript after build-time
2. Simple syntax for using sidenotes
3. The resulting markup is somewhat semantic

Quick Demo

On desktop, this text fills the right margin, and on mobile, it simply collapses into a box below the relevant paragraph.Like this! ~~formatting~~ works here too.

Remark Plugin (Not Recommended)

I originally wrote this blog using Remark. The common, hacky way to build custom components using Remark is to create a codeblock with the language set to a specifier for your component instead of a real programming language.

Take, for example, if we wanted to add a newsletter button to our page:

# My title

This is a button:

```newsletter-button
Subscribe to my newsletter!
```

We would then write a Remark plugin that checks all code blocks in the syntax tree where lang is newsletter-button and then swaps the code block's node out for a custom HTML node. The code block node is commonly overloaded for custom components since it allows for arbitrary content.

This is pretty much exactly what I did when building sidenotes with Remark. If you just want to see the Gatsby plugin itself, all of it can be found here. I no longer recommend this approach. Keep reading for a more idiomatic method of implementing sidenotes.

With MDX

MDX is a markup format that allows you to use JSX within markdown. It blends rich-text and dynamic presentation methods. As a result, we only use forceful syntax when necessary. If you are used to writing React like I am, this leads to a very comfortable writing experience.

Below is an example of a React component (Sidenote) being used in an MDX file.

<Sidenote content={"An interesting tidbit about foo!"}>
  Something about foo.
</Sidenote>

If you need it, the Sidenote component is implemented as follows:

const Sidenote: FC<SidenoteProps> = ({ children, content }) => (
  <div className="sidenote-wrapper">
    {children}
    <aside>{content}</aside>
  </div>
);

Limitations

While this approach is simple, it is also naive. It requires some manual restraint, as overlaying is not dealt with in any way. In other words, if there are many sidenotes in the page gutter, then they will stack on top of one another. My writing style does not lean on sidenotes too hard, so this works out.

A way around this is to provide some API for specifying the offset of the sidenote. Below is a vanilla CSS solution that uses CSS variables to offset the sidenote. Alternatively, you could use a prop in the MDX component to specify the offset using styled-system, Tailwind, or whatever you prefer.

<Sidenote content={"An interesting tidbit about foo!"} offset={3}>
  Something about foo.
</Sidenote>

/* Map attributes to CSS variables */

[data-offset="1"] {
  --offset: 1;
}

[data-offset="2"] {
  --offset: 2;
}

[data-offset="3"] {
  --offset: 3;
}

...

/* Use CSS variables to offset the sidenote */
.sidenote-wrapper {
  margin-top: calc(var(--offset) * 1.5rem);
}

Gaining alignment in any kind of interview is difficult. As of now, most of my experience comes from recruiting for undergraduate clubs for student designers, developers, and 'product managers' [^1]. I doubt these roles are as competitive as they are at Stripe, but in smaller pools, you get to assess candidates in ways that are not possible at scale.

[^1]: We call them 'product managers', but they are really just project and people managers. I think conflating the two roles is probably a mistake, but it works when you want a no latency between scoping, delegation, and delivery.

This post is a collection of thoughts on problems with the technical interviewing and application processes I ran at Hack4Impact and Illinois Labs.

Problems With Hiring

Long term vs Short term Problems

Interviews can only test how individuals solve problems in the short term, but are accepted as a predictor of long term problem solving ability in lieu of experience. The closest approximation possible is taking a problem directly the job and facilitating a candidate's approach. Here, the gap still persists as a time limit alongside unfamiliarity which can hurt candidates, yet has little affect on job performance. Inversely, some candidates may be great at debugging code academically, but fail to design a new system.

Experience Bias

Generally, a poorer interview is passable alongside demonstrated experience. An issue we face by having a candidate pool of undergraduates is a lack of experience. Candidate years typically skew right, with a larger amount of underclassmen applying. A lack of experience in our applicants can make some excelling individuals shine, but will generally shift more weight to an interview. Experience bias puts leverage on the interview gap.

Project Assessment

Projects are an incredibly difficult way to assess an applicant's technical skills. There is no value in rewarding applicants for having cool project ideas. Ideas are cheap, implementation is not. Following this line of thinking, we should probably read their code. Here we run into our next problem: there is no timely, or meaningful way to assess implementation without understanding the product decisions made. This rabbit hole is not worth exploring. I recommend using projects as a surface level heuristic for capacity to learn. Instead of trying to figure out how "good" a project is, see what types of technologies this candidate is picking up, how fast they are doing it, and if they can briefly explain their choices.

What to do

Given these limitations, what actually works?

Some signals I've found are: great personal websites, having strong opinions, and just being enthusiastic about the work in conversation [^2]. What you are really trying to figure out is, respectively: attention to detail, deep engagement with work, and ability to contribute to a team.

[^2]: It's hard to think about interviewing without considering the meta. There are certainly people who are just good at "interviewing", but not fun to work with. After a while of either interviewing or talking to the candidate it's pretty obvious who is who.

Interviews should feel more like technical conversations than interrogations. The best signal comes from learning how someone thinks through a problem they have already solved.

I've been interviewed this way at startups: a conversation about something I've built and work through the decisions made. Even if the interviewee hasn't built a software product (or any product!), they should show they have gone deep. Having tried to fake it, I've found this interview is pretty hard to brute force as it lets one probe decision-making, not just outcomes.

I think it's hard to recognize great talent (besides referrals) without a good amount of experience with the role or profile. Having taste essential. The interview gap will always exist, but supplementing with other signals is a good way to fill it.

Dropping the 'I'

The title practice and inspiration for this write-up concern the 'I'-prefixed naming conventions some employ when writing TypeScript and other strongly typed languages. The vast majority of Interface usage I have come across is operational as a type. After all, vanilla JavaScript deals with objects as dictionaries rather than classes, so this practice carried over with TypeScript's interfaces.

Consequent to the semantic use of interfaces, naming one with an 'I' (e.g., interface IFoo { ... }) as opposed to without it (e.g., interface Foo { ... }) is not only redundant as the type is strongly specified, but harmful to readability and debugging. Consider the following:

interface IVehicle {
  name: string;
}

interface ICar extends IVehicle {
  make: string;
  year: number;
}

Nothing about these definitions alone is wrong, but let's step through an example of their use.

// initialize a car
const myCar: ICar = { name: "My Car", make: "Honda", year: 2000 };

// initialize an array of vehicles with `myCar`
const myVehicles: IVehicle[] = [myCar];

myVehicles; // [{ "name": "My Car", "make": "Honda", "year": 1998 }]

In the above example, the 'I'-prefix stands out, more so than with the original definitions. This presents a consistency issue, which turns out to be one of the more fundamental issues with using this convention in TypeScript. If this representation of a car needs to be ICar, should myCar not be instantiated as myICar? I say the answer to this question is strong 'no', but recognize there is a bigger issue at play.

It is likely that somewhere along the line of creating many ICar and IVehicle references, the author drops the prefix, as in the example above. When scanning through the prior example, nothing pops out as distinctly incorrect or even poor practice. If most programmers would be fine scanning through this snippet and leaving myCar named as-is, then the issue lies within the naming of the interface itself. Its real purpose is as a validated key-value store (à la struct in C).

By dropping the 'I', code is more consistent and readable at the sacrifice that your type is implemented as an interface, but this caveat is not all that important for most TypeScript developers.

Broadly, a simple way to think about how prefixes in naming should work is to think about how a piece of code is used rather than how it is implemented. No user cares whether the web app they do their taxes with is written in Java, or Ruby, or even Haskell, only that it works and is performant enough. By the same token, it probably does not keep an engineer up at night not knowing if the List interface they interact with is implemented as a linked-list or resizable array.

When Using Prefixes

Drawing directly from the previous example, there is a reason that most languages implement a list interface as List<T> as opposed to IList<T> because if they perform the same semantic purpose, the underlying implementation is not all that important. C# is notable exception. The Microsoft .NET style guide popularized type prefixes. By-the-book workflows led to overuse of the 'hungarian' convention A good time to use prefixes, however, is in the opposite case: a semantic disagreement between two definitions with similar contents.

Take, for example, loading in data from a spreadsheet whose rows need to be displayed in a web table. The head of my original data could look like the following:

| product_id | price | | ---------- | ----- | | 1097B | 40.25 | | 1024D | 35.00 | | 1112A | 28.00 | | 1024D | 35.00 | | ... | ... |

To match this table schema, I have defined an interface below and used it to display.

interface Row {
  product_id: string;
  price: number;
}

This type definition is perfect for displaying the data directly from the spreadsheet, but what if we want to combine all duplicate entries and store quantity as a column? We define another interface to keep quantity associated with a product. The bigger question is what to call this new interface.

This is where prefix naming can be incredibly helpful: in situations where the computer cannot distinguish the meaning between two pieces of data. Let's shelve the table-row example for the time being. The snippet below centers user scores around an average as part of a rating system.

#include <iostream>

...

double averageScore = 3.36;
double uncenteredUserScore = 4.00;

double centeredUserScore = uncenteredUserScore - averageScore;

cout << centeredUserScore << endl; // 0.64

To the compiler, this sequence of operations is assignment and subtraction, so our prefixes make no difference. Each value is a floating point, so prepending 'D' as a prefix (e.g. DScore) is distracting. Instead, prefixes are here to provide context to values, which, when later referenced, can make their misuse clear to any reader.

A statistical analogy is a great one. Statisticians work with calculus and linear algebra, but they are really in the business of forming conclusions from datasets through contextualization. In the same way, it is the programmer's job to provide the context a computer cannot understand. This is why semantic prefixes are so powerful for both debugging and readability.

Returning to the web table exercise from earlier, we can now use prefixes to create two versions of our type. The former type could be renamed to rawRow, and a new one, containing any new fields necessary, could have the name processedRow. Having many named variables also assists in leaning into functional programming for easier debugging.

interface rawRow {
  product_id: string;
  price: number;
}

interface processedRow extends rawRow {
  quantity: number;
}

const processedRows: processedRow[] = rawDataFromSpreadsheet
  // Add new field for all data types
  .map((elem) => ({ ...elem, quantity: 1 }))
  // Process duplicates into single entries with increased quantity
  .reduce(function (accumulator: processedRow[], cur: processedRow) {
    let found = accumulator.find(function (elem: processedRow) {
      return elem.product_id === cur.product_id;
    });
    if (found) {
      found.quantity += cur.quantity;
    } else {
      accumulator.push(cur);
    }
    return accumulator;
  }, []);

Now, as long as we reference the correctly prefixed value when accessing this data, we should be able to put together a table similar to the following:

| product_id | price | quantity | | ---------- | --------- | -------- | | 1097B | 40.25 | 1 | | 1024D | 35.00 | 2 | | 1112A | 28.00 | 1 | | ... | ... | ... |

In Practice

While I am of the belief that I made a strong case for not using type prefixes, there is nothing more valuable in code readability than consistency. The team I work on uses 'I'-prefixes for interfaces within our TypeScript frontends. When developing, it's important to use conventions from your style guide. An abstract "best practice" is not valuable until it is consistent. With many projects, sticking with what engineers find comfortable will help teams move fast. In some cases that calls for keeping the 'I'.

What is Functional Programming?

An often used and concise description of functional programming is "a paradigm involving functions as first-class citizens, or in short first-class functions". To break this down a bit further for the uninitiated, a function is first-class when it is able to be used as if it was a variable. This includes being returned, passed as an argument or reassigned.

For example:

// where `a` and `b` are numbers
const add = function (a, b) {
  return a + b;
};

const calc = (operation, a, b) => {
  return operation(a, b);
};

// Pass `add`, `1`, and `2` as arguments to the `calc` function
calc(add, 1, 2); // = 3

In this case add is declared as a traditional function and assigned to a variable, and it can be invoked directly with add(a,b). add can also be passed as a variable (as in calc()). While this scenario is just overcomplicated arithmetic there are actual advantages to the functional paradigm. Note we avoid defining variables with 'var' or 'let' and instead opt for 'const' which is cannot be reassigned, I'll talk more about this shortly.

Advantages of Functional Programming

Functional programming is nothing new. Being modeled after lambda calculus and mathematical functions, functional programming languages like LISP and Haskell have been around for over 60 and 30 years respectively. While you may not see these names crop up often they still have they still have their uses and for good reason. Some companies are even using Haskell for a lot of their infra. Check out mercury.com and hasura.ioFunctional programming poses advantages that, in practice, are unique to the paradigm.

No Side Effects & Debugging

Functional programming opts for programming without side effects. Much like a mathematical function, functions take input(s) and return one or more outputs. When writing code with functions with no side effects, also known as pure functions, a program will often become much easier to debug. Data and state are received and returned throughout a series of breakpoints (i.e. pure functions) which allows a programmer to pinpoint errors with ease.

Code Readability

One caveat of writing pure functions and reducing state changes is allocating memory. Luckily JavaScript garbage collection is far from expensive, making it a great playground for exploring the benefits of functional programming. One of these benefits is readability. Functional programming allows for abstract concepts to be condensed and obscured for clean, very readable code. A great example of this are JavaScript ES5's Array methods like map() and filter().

Since React 16.8, the framework has supported, and has made it clear they intend to move to, using functions from components and functional hooks for state management. Both of these implementations replacing their class or object-based predecessors. The React team made this change to provide a simpler and more readable development experience for frontend engineers. Further, understanding functional programming can prove useful when writing clean code in React.

Why JavaScript and ES6?

While all these ideas may sound great something that may have come across your mind is 'why JavaScript'? The language is extremely popular due to its dominance on the web, not because it is very readable or logical. These conditions allow for many inexperienced and experienced programmers alike to write JavaScript in completely different ways. By moving towards a functional paradigm streamlining repositories becomes a lot easier. Clearly, this would be true of any style guide or paradigm, but there are other, more compelling reason, to write functionally in ES6.

JavaScript Supports a Variable Number of Arguments

JavaScript is somewhat unique in the way it handles arguments in functions. It essentially allows for a variable amount of predefined, or undefined, arguments to be passed to a function and will not throw an error unless the compiler flags a variable a required (e.g. it is returned or directly manipulated). This allows functions to be written with either truthy values or JavaScript's implicit iterable arguments array as seen in the following example.

/*
 *  returns the sum for any length of numerical arguments
 */
function sum() {
  let sum = 0;
  for (const arg of arguments) sum += arg;
  // iterate through JavaScript's implicitly created `arguments` array
  return sum;
}

sum(); // = 0
sum(1, 2, 3, 4); // = 10

Writing Recursively

Most newcomers to the functional paradigm question the efficiency of recursion and that uncertainty is well-founded. In most popular (read: object-oriented) programming languages like Python, C/C++, or Java, recursion can definitely bloat the call stack. This, however, is resolved with tail call optimization, which enables recursive functions calls without adding a new stack frame to the call stack which will help avoid a RangeError. Also called tail call elimination, this technique has been added to the JavaScript specifications with EMCAScript 2015 (ES6) and is available in Node.JS. This type of optimization is present in strictly functional languages like Haskell. Unfortunately most browser engines (with the odd exception of Safari) have not implemented this part of ES6. While this is concerning for functional JavaScript right now, it is also a clear sign of the direction the language is taking in shifting its focus paradigm.

Why Not to Use Functional Programming

As any computer scientist should know, throwing new, exciting, or complex technology at one's issues is not the most productive way to go about solving a problem. While functional programming can be a valuable item in a developer's toolbox, the most valuable tool, as corny as it sounds, is judgement. Knowing more paradigms can also allow one to both find styles they like to write in themselves and jump into another developer's codebase with ease.