Implementing a PoC for this, and stumbling upon a circular dependency issue between Layout and its import of defaultOptions, and propAliases and its import of transformNumeric.

Underlying cause is that transformNumeric imports Layout for default unit check. That creates the following import order:

Layout -> defaultOptions -> propAliases -> transformNumeric -> Layout (circle)

I would love to make transformNumeric pure, accepting default unit via arguments. This would resolve the circular dependency, and make this util more reliable.

This may burst a more broad discussion on how to effectively distribute global layout settings throughout the library's internals.

I don't know any library that exposes a way to change its api. How is this documentable/ typable?

I think it's more common to have a separate npm package with its own api and documentation. Like bootstrap-atomic-layout, which api would be more inspired by the bootstrap utils api.

It's not a change, it's extension of the API with the options you need. API, in this case Responsive props API, behaves as per spec in documentation, but you can configure your custom aliases for any purpose. It's very similar to such API from styled-system.

Once useResponsiveProps React hook has been introduced in 0.8.0, support for the custom prop aliases has been put under question.

Although custom prop aliases can be of practical use, I'm strongly convinced that it would do more harm, if introduced. Atomic layout encourages a separation of concerns by splitting the visual styling and positional styling. It felt uncomfortable for me at first too, but doing project after project following this separation I can hardly notice it now. Moreover, styling has become significantly easier.

Why custom prop aliases is not a good idea?

Because it allows (and, thus, encourages) mixing visual and positional styling. This contradicts the core message of the library, which is the separation of concerns. On practice that would make Atomic layout a formless box to stuff all your styles into. I don't find this as a good styling encouragement, or even an implementation approach.

How to substitute custom prop aliases?

Nevertheless, I can share the need to benefit from integrating certain custom styles with Atomic layout. During my work it mainly comes down to applying certain styles conditionally using Responsive props.

Using useResponsiveProps hook can simplify responsive values declaration and make it aligned with the breakpoints:

import styled from 'styled-components'
import { useResponsiveProps } from 'atomic-layout'

const StyledText = styled.p`
  font-size: ${({ size }) => size}rem;
`
const Text = (props) => {
  // This processed the incoming props and returns any responsive props.
  // So it's possible to suffix any props with a breakpoint name, thus, making
  // any prop responsive.
  const { size } = useResponsiveProps(props)

  return <StyledText size={size} />
}

// Usage example
<Text size={1} sizeMd={2} sizeLg={3} />

With the introduction of #194 the declaration may become less verbose. The only difference with this way of applying responsive values is that the mapping between a prop name and what it actually does is up to the end consumer (which is rather a good thing).

Summary

That being said, I don't think that custom prop aliases is a good idea. Atomic layout should support a sufficient amount of prop aliases (CSS properties) for effective layout positioning. If any props are missing, please file an issue to add them.