Responsive Design

Design must adapt to screen sizes. There’s no escape.

Users expect layouts to feel correct on small phones, large monitors and everything in between.

Shilp CSS provides a small, intentional set of breakpoints and a clear, mobile-first approach to help you handle this cleanly.

Pre-requisites

Before anything else, make sure meta viewport is present in your HTML's <head>. Without it, responsive layouts will not behave as expected.

index.html
<!DOCTYPE html>
<html>
	<head>
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
	</head>
	<body>
		...
	</body>
</html>

Mobile First Design

Shilp CSS is mobile-first.

That means:

Base styles apply to small screens by default
Larger screens override them explicitly

Think of it like this:

Design for mobile first
Add complexity only when screen space increases

This avoids writing “undo” styles later.

Default Breakpoints

Shilp CSS ships with a minimal, practical set of breakpoints.

Variant	Width
xs	375px
sm	640px
md	768px
lg	1024px
xl	1280px
mac	1440px
max	1920px

JUST DO NOT FORGET TO TEST THAT ONE ODD SCREEN.

Working With Breakpoints

You can write responsive rules using @screen <variant> { ... } and this is replaced with @media (<condition>) { ... }.

info

Shilp CSS does not automatically add @media screen. You can wrap it manually using:

@env screen {
	@screen md {
		...
	}
}

You don’t need screen because @media defaults to all media types, and in practice your styles are meant for screens anyway.

Use print only when you want separate styles specifically for printing (e.g., hiding UI, adjusting layout for paper).

There are few approaches:

1. Minimum Width

This is recommended and mobile first approach.

@screen md { ... } → @media (min-width: 768px) { ... }

2. Maximum Width

This is not recommended and use it only if there's no other way.

@screen max-md { ... } → @media (max-width: 767px) { ... }

Here, max-md means below md

3. Width Range

Ranges are important when a style is valid only within a specific window, not beyond it.

@screen md:mac { ... } → @media (min-width: 768px) and (max-width: 1439px) { ... }

Here, max-* maximum is not allowed inside range. it doesn't make semantic sense.

Why Mobile-First Matters

Mobile-first gives you:

A stable base
Fewer overrides
Cleaner cascade
Better performance defaults
Clear upgrade path for larger screens

You design for small screen first. Then progressively enhance.

This reduces accidental complexity.

How to Design Responsively

Responsive design in Shilp CSS follows a simple pattern:

Define the mobile layout first
Override only what changes
Add precision only when needed

Step 1 - Start With Mobile

Write the smallest, simplest version first.

navigation.css
nav {
	@layout is-flex;
	@flex flow-col;
	@space p-4 gap-4;
}

This applies to all screens by default, including mobile.

You do not write a mobile breakpoint. Mobile is the baseline.

Step 2 - Enhance at Larger Screens

Now ask: what changes at md?

navigation.css
nav {
	@layout is-flex;
	@flex flow-col;
	@space p-4 gap-4;

	@screen md {
		@flex flow-row;
		@space p-6 gap-6;
	}
}

Here, We override only what changes.

Step 3 - Add Precision Only When Needed

If something needs special handling for a range:

navigation.css
nav {
	@layout is-flex;
	@flex flow-col;
	@space p-4 gap-4;

	@screen md {
		@flex flow-row;
		@space p-6 gap-6;
	}

	@screen md:xl {
		@text size-lg;
	}
}

Avoid adding breakpoints “just in case”. Add them only when layout truly changes.

info

Here, for ranges, we have defined separate mixin.

@screen md { ... } - targets ≥ 768px
@screen md:xl { ... } - targets 768px to 1279px

In other way, It can be written as:

@screen md {
	@screen max-xl {
		...
	}
}

But, this is intentionally avoided.

Shilp CSS do not recommend nested breakpoints. use ranged breakpoints instead.

When Layout Gets Complex

If responsive logic starts growing too large:

Extract components
Use clearer class boundaries
Make sure there are no nested breakpoints
Re-evaluate layout assumptions

Responsive design is not about adding more media queries. It’s about simplifying structure.

Note

Must check Container

Common Mistakes to Avoid

Avoid writing desktop first and patching mobile later
Avoid overusing max-* breakpoint variants
Avoid adding breakpoints for minor spacing tweaks
Avoid duplicating layout logic across ranges
Avoid forgetting to test real devices

Responsive CSS should feel progressive, not reactive.

Customization

You can extend or override breakpoints in shilp.config.js.

warning

Values must be string with px unit.

shilp.config.js
const shilpConfig = {
	source: "react",

	extend: {
		theme: {
			screens: {
				xs: "360px", // override: 375px to 360px
				mid: "1536px", // new breakpoint
			},
		},
	},
};

export default shilpConfig;

Keep the breakpoint list small and intentional. Adding too many defeats clarity.

Container Queries

Container queries are not included by default.

They fall slightly outside the current Shilp CSS compatibility baseline.

You can still use it with raw CSS if needed. No restrictions.

info

It is in roadmap and will be added progressively.