Replit is an online workspace where Replit Agent, an AI assistant, builds a website or app from your description, runs it and publishes it. Agent sets up a lot by itself, but it builds what you ask for: if accessibility is not part of the request, it is left to chance. This guide shows which problems to watch for, how to write instructions Agent reads with every request, and how to check the published site.
What Replit Agent builds
For websites and web apps, Agent commonly uses React (a widely used way to build web pages) styled with Tailwind CSS, with interface parts from shadcn/ui, a collection of ready-made menus, dialogs and form fields. Behind it there is usually a small server written in Node.js and a PostgreSQL database. The exact choice depends on your request, and Agent can also build mobile apps. ibin checks web pages, so this guide is about sites that open in a browser.
The shadcn/ui parts are a good start: their dialogs, dropdowns and tabs come with keyboard support and the right information for screen readers (software that reads the screen aloud). Many Replit web apps are also single-page apps: the browser loads one page and swaps the content when you click a link. That feels fast, but causes the first two problems below.
Problems that often appear
These patterns come up regularly. Clear instructions prevent most of them.
- One title for every screen. In a single-page app, the title in the browser tab often stays the same on every screen. Screen reader users hear that title first and use it to know where they are.
- Focus that stays behind after navigation. After a click on a menu link, the new content appears, but the keyboard position stays in the menu, so keyboard and screen reader users do not notice that anything changed.
- Icon-only buttons without a name. A menu, close or delete icon that a screen reader announces only as “button”.
- Errors that only appear as a toast. A toast is the small message that slides into a corner and disappears after a few seconds. People miss it, and nothing next to the field says what to fix.
- Muted text with too little contrast. Soft grey text on white or light grey cards.
- Clickable rows and cards. Table rows and cards in dashboards that respond to a mouse click but cannot be reached with the Tab key.
Where to put permanent instructions
Replit Agent reads a file called replit.md in the main folder of your project. According to Replit’s documentation, Agent creates this file when it starts a new project and includes its contents with every request, to understand your preferences, project structure and coding style. You can edit it like any other file.
- Open replit.md in the top-level folder of your project. If it is missing, create a file with exactly that name there; Agent only finds it in the main folder.
- Paste the block below at the end.
Agent can also update replit.md itself. Look at the file now and then to make sure your accessibility section is still there.
Replit also has skills, reusable instructions you install in a project, but for a short list of rules replit.md is the simplest place.
Instructions for Replit
Paste this into replit.md. Change the language code if your site is not in English.
## Accessibility requirements (do not remove) Follow these rules in every change. Aim for WCAG 2.2 level AA. - Use semantic elements: header, nav, main, footer. Use real links for navigation and real buttons for actions. Never put a click handler on a div, table row or Card. If a whole card is clickable, put a real link inside it. - Every icon-only button has an aria-label in the site language, such as "Delete invoice". Mark the icon aria-hidden. - Every form field has a visible label connected to it. A placeholder is never the only label. Errors appear as text next to the field, not only in a toast. - Text contrast is at least 4.5:1, large text and icons 3:1, in light and dark mode. - Keep a clearly visible focus style on every link, button and field. - Set lang="en" on the html element. Update the document title on every route change, for example "Invoices – My App". - After a route change, move focus to the main heading of the new screen. - One h1 per screen, headings in order. - Keep the keyboard behaviour of shadcn/ui and Radix components. Dialogs close with Escape and return focus to the button that opened them. - Meaningful images need alt text; decorative images get alt="". - Respect prefers-reduced-motion for animations. - Add a "Skip to main content" link as the first item on every page.
Follow-up prompts for common problems
After a check, ask for one fix at a time. Replace the parts in square brackets.
- Titles and focus: “When I go to another screen, the browser tab title stays the same and the keyboard focus stays in the menu. Give every screen its own title and move focus to its main heading after navigation.”
- Icon buttons: “Give every icon-only button in [the invoice table] a name that says what it does, including which item it acts on. Do not change how they look.”
- Toast-only errors: “In [the sign-up form], show each error as text below the field it belongs to, connected to that field. Keep the toast only as an extra.”
- Contrast: “Darken the grey text on [the dashboard cards] until it reaches at least 4.5:1.”
- Clickable rows: “I cannot open [an order] with the keyboard. Replace the click on the table row with a real link in the first cell.”
Agent can test whether features work, but working with a mouse is not the same as working with a keyboard. Ask explicitly: “Test the main flow using only the keyboard and tell me where it gets stuck.”
Publish and check
ibin checks pages on the public web, so it needs an address anyone can open. Replit’s publishing guide describes the steps.
- Skip the development preview. The preview address you see while building is temporary. Check the published app.
- Publish. Select Publish at the top right of the editor. The address ends in .replit.app.
- Choose public access. Replit offers Public, Password protected, Workspace only and Invite only. A checker cannot sign in or type a password, so choose Public.
- Check the page with ibin. Start with the home page, then your most important form or screen.
- Paste the fix into Agent. Each problem in the report has a “Copy instructions for an AI tool” button. Paste the result into the Agent chat. It asks for a fix in the app itself.
- Republish and check again. Changes in the editor do not reach the live app until you select Republish. The address stays the same.
- Check more pages. Sign in to check up to 200 pages of the same site, and turn on weekly checks to catch problems that come back.
Screens behind a login cannot be checked from outside, so test those yourself with the keyboard. Automatic checks find roughly a third to half of all problems; also do the 10-minute keyboard test.
What Agent cannot judge
Agent can write a description for a photo, but it cannot know whether the photo shows your product, your team or just a mood. It cannot tell whether five buttons called “View” make sense when a screen reader lists them, or whether your text is clear in a second language. Review image descriptions and link texts yourself whenever you add content. ibin’s optional second look from AI rates these on a scale from 1 to 5, so you know where to start, but a person makes the final call.
See also the overview for AI builders and the repair guides, for example on form fields without a label and page titles.
Check your Replit app
Publish your app with public access and check a page for free with ibin. Copy the instructions for each problem into Replit Agent, republish and check again until the urgent problems are gone.
See how your own site does
Check a page for free, without an account. You get a plain list of what to fix first, with pictures of where each problem is.