Nikki Katsutani

Wow! That design process was a doozy. But you've made it! Time to kick off development! But… Now what? How do you translate your cutting edge and beautiful designs into concrete tasks for your development team? 

Here at Beta Acid, we specialize in doing this very thing. Here are some helpful tips on how we approach writing User Stories for front-end development. This approach can be used for all types of front-end projects including responsive web apps, native mobile apps, etc. 

### Tips Before Starting

1. We don't care about any fancy methodologies or frameworks (gherkin is only a type of cucumber to us). The point is communication so use whatever works best for your team. 
2. Designs are never final so don't assume that they are. Designs tend to continue to evolve even after they are approved. Select an approved version and use that as a reference for your story. Plan for adopting changes through an iterative development process. 
3. Don't assume that something is "standard" and will be built by default. Unless explicitly documented, you risk the chance of something being missed.

### Purpose of User Stories
The purpose of a well written User Story is to communicate design and product requirements for the piece of functionality the Engineers are building. It should be the single source of truth for Engineering during the development process.

User Stories should break down designs into bite-sized pieces of development that can be tackled by a single engineer. If it is helpful for your team, you may also want to consider limiting User Stories to, at most, one day of development time for a single engineer. This prevents User Stories from getting too large/complex which could impact both development and QA. 

User stories are also heavily used by Quality Assurance teams. A well written User Story can be used as a checklist of what to test and how to test it. It sets expectations with your QA team and helps to ensure a smooth and efficient QA process. 

### Who Should Write User Stories 
Anyone with adequate knowledge of the product and design requirements can write User Stories for development. It is typically the responsibility of a Product Owner or Product Manager. However, writing User Stories can also be completed by a Project Manager or Engineer with the proper knowledge and background. 

### Key Elements of a Well Written User Story

#### Screenshot of the screen from your designs 
You can also supplement the screenshot with a link to the full design file. However, providing only a link to the design is not recommended. A screenshot draws a line in the sand of what the engineering team will build. When the designs change (and they will), there will be a misalignment between the written User Story and the design file. You also lose the history of what design was used to write the User Story. With a screenshot of the designs in your User Stories, you create a single source of truth for what is to be built and retain history which will reduce the risk of a confused Engineering team.

#### Content and Functionality
For simple screens or features, look at the screen designs from top to bottom. As you're scanning the screen, write down everything that you see and what it does. It is important to be as explicit, detailed, and prescriptive as possible. In conjunction with the design screenshot, the developer should have everything they need within the User Story to understand exactly how the screen should appear, what functionality it should have, and exactly what  happens when the user interacts with any part of the screen. For more complex features, use the same process as above but it may be appropriate to break the features down into smaller stories.

#### Don't forget about:

- User States. Does the functionality or screen change based on the User's status, role, or other attribute? For example, the User is logged in vs. logged out, the User is an administrator, the User has completed a particular task, etc.
- Validation. What information should be validated or checked? If the information is incorrect, what should happen? Consider complex validation scenarios as well; does one field depend on another?
- Loading States. What does the screen, its contents, or CTAs look like when loading occurs?
- Empty States. Is there a situation where a list of data or other information may not be present? If so, how should the screen handle it?
- Hover States. If the user hovers over a component with their mouse, what should happen? 
- Error States. What should happen when an error occurs? 
- Analytics. What analytics should be captured on the screen?
- Keyboard Types. For mobile apps, if a keyboard pops up for an input field, what sort of keyboard should be displayed? Should it have a "Return", "Next", or "Go" button? Should it be restricted or are all characters allowed?
- Animations. Does something on the screen automatically move? If so, describe exactly how it should move. Or, include the animation file that should be used for development. 

### An Example
Below is a real-life example of a story we wrote for the Login Screen of a mobile app build.

<div style="background-color:#f0f5fa;padding:8px 24px;">

#### Header
"Back" CTA to the left. When tapped the user should get to the previous onboarding screen.
ABC Company logo on the right. When tapped, the user is directed to the Home screen.

#### Screen Contents
Screen will show a "Login" title. 
A text input field with the title "Username"
- When the user taps into the field, the default keyboard should appear. 
- On the default keyboard "returnKeyType" should be "next". When tapped the user will lose focus of this field and focus will move to the next field "Password".
A text input field with the title "Password"
- When the user taps into the field, the default keyboard should appear. 
- On the default keyboard "returnKeyType" should be "done". When tapped the user will lose focus of this field and the keyboard disappears.
- Password text input field will be obfuscated by default and show an open Eye Icon. 
- If the user taps the open Eye Icon
        - Change to a closed Eye Icon
        - Display the password as plain text (not obfuscated)
- If the user taps on the closed Eye Icon 
        - Change to an open Eye Icon 
        - Obfuscate the password
A "Sign In" primary CTA
- The CTA is always in an active state
- When tapped it will make a call to the Login endpoint and the loading indicator will appear.
- Client side validation:
        - If the user taps "Sign in" but the username and/or password text input fields are empty. 
                - Display error messages under each empty field: 
                - Username: "Please enter a username" 
                - Password: "Please enter a password".
                - Each empty field will appear outlined in red.
- Endpoint responses:
    - [URL or relative path of the endpoint - removed for confidentiality]
    - 200 response
        - if (mfa_setup_required = true) navigate to MFA screen
        - else: store the 'token' in secure storage and navigate to the dashboard screen.
    - 400 response
        - Display 'message' value from response

#### Footer
- "Privacy Policy" CTA at the bottom right side of the screen. 
- When a user taps on it, they will be able to see the Privacy Policy, shown in an in-app browser.

#### Analytics
- Record a Page View event
- Field validation errors for username and password fields
- Tapping the "Sign In" CTA

</div>

### Pro Tips

##### Use Component Names
If you are using a design library or design system, use the actual name of a component in your User Story. This will ensure that the correct component is used.

##### Capture All Error States
Work with your Engineering team to get a list of all errors that can occur on a particular screen. Make sure your User Story documents all possible errors in order to ensure that every scenario is handled gracefully. 

##### Order your Epics for Development
The order in which you tackled the design process may not translate well for development. Have a chat with your development team to sequence your Epics for development in the most logical way possible. Often, the first three epics are:
- Design library and common components: build it once then reuse them over and over again. It will speed up the rest of development.
- Global navigation: so you have a way to navigate through your app to different areas of functionality
- User creation and authentication: in many apps, you can't do much else if you don't have a user to do it with. 
- After that, it really depends on your product so rely on your engineering team for guidance. 

#### Timing of Back-end Development
The following discussion of team sequencing probably deserves an entire article of its own. Where possible, we try to keep the back-end team two epics ahead of the front end team; sometimes this means doing back-end work while designs are still in progress. This allows the front-end team to hit the ground running as soon as designs are approved.

Yes, you can use mock endpoints in a pinch but this approach adds two phases of work to your schedule: building mock endpoints and re-testing against real endpoints when they're ready. It also often causes a bunch of re-work if your API contracts are not solid (thus your real endpoints end up being different from the mock endpoints you built).

### Is it worth it?
A well written User Story does take (a lot of) time. Sometimes, especially for very small, close knit teams that have worked together in the past with solid relationships between product, design, and engineering, the level of detail in a well written User Story is not worth the amount of time they take to write. However, there are many scenarios where well written User Stories are highly valuable. A couple scenarios are:
Large teams where there might not be very much communication between a product owner or designer and the engineers, 

Teams where new engineers are being onboarded mid-project and lack historical or domain knowledge.
In these cases, a well written story is your go-to tool to communicate requirements so the detail is crucial. Evaluate where your team is on this spectrum and adjust accordingly. 

### Conclusion
This is how we do things at Beta Acid, but it's not a one-size-fits-all solution. We believe adaptability and flexibility is critically important. For every project we evaluate how to be as effective as possible given the variety of client and team needs. Sometimes, a well written User Story creates efficiencies that far outweigh the time commitment to write them. 

Want to learn more about working with us? Reach out to: <a href="mailto:hi@betaacid.co" style="color:#B400FF;font-weight:600;">hi@betaacid.co</a>.

Writing User Stories for Front-End Development

Fábio Colombo

A serverless architecture allows you to configure your system once and avoid most of the maintenance and operational work. Serverless architectures will generally scale well and without any operator interaction. Most serverless architectures are based on cloud services priced based on how much you use the service. AWS Lambda, API Gateway, CloudFront, and S3 are examples of this. AWS Lambda pricing is a product of the run time of your function, i.e. how long it takes to load and run and the amount of memory and disk used by the function. API Gateway and CloudFront pricing are both the sum of requests handled and data transferred. S3 pricing depends on the amount of data stored (as well as how this data is stored) and the amount of data transferred.

This pricing model is great for projects just starting out since they provide a robust infrastructure that requires little setup and maintenance while likely costing less than running a traditional infrastructure based on your own VMs or on-premise.  Although serverless architectures require less setup and maintenance, it is still important to check if your costs are scaling well with increasing traffic. In this blog post, we will look at a cost reduction analysis for one of our projects and how you can apply this to your own projects.

### Analyzing your Bill

Cost analysis always starts with the bill. AWS, GCP, Azure, and other cloud providers have services specifically for cost analysis. AWS provides the [Cost Explorer](https://console.aws.amazon.com/cost-management/home) dashboard, which allows you to filter your costs by service, such as Lambda, API Gateway, S3, etc., and can also project month-end costs based on your previous usage. Google Cloud has a similar feature in [Cloud Billing](https://cloud.google.com/billing/docs), as does [Azure](https://learn.microsoft.com/en-us/azure/cost-management-billing/) and many other cloud service providers. Learning to use the features available for your provider is an important step to understanding and optimizing your cloud infrastructure costs.

Another important aspect of cost analysis is how you plan to distribute costs among your projects. By using a different AWS Account (or GCP project) for each project, you can have a clearer picture of costs per project. AWS allows you to have linked sub-accounts so that billing is centralized in a single account, but resources can be split up among different accounts. This is great for cost analysis as well as for security, as credentials can be managed with greater ease in each sub-account. You can give a team greater control over their specific account or project without having to worry about them accidentally messing up infrastructure managed by a different team.

If creating new accounts or projects is not an option, you still have options for splitting up costs. AWS allows you to use [special tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) for cost allocation. GCP allows you to [add labels to cloud resources](https://cloud.google.com/blog/topics/cost-management/use-labels-to-gain-visibility-into-gcp-resource-usage-and-spending) so that you can later filter costs using these labels. Depending on your cloud infrastructure, you may need to modify your code to use logs or register metrics to allocate costs.The AWS, Azure, and GCP cost management features also allow you to create budgets and automated alerts to inform you beforehand that you are spending more than you expected, giving you time to take action to reduce your costs.

Although learning about the newest technologies may seem more exciting than learning how to navigate and query cost data, this is an essential skill if you want to optimize your infrastructure. Knowing how each cloud service is priced will help you better plan the correct infrastructure for each use case. Knowing how to analyze costs will allow you to focus your optimization efforts on the services that make up the largest percentages of cloud costs. Like in software optimization, the final savings will be a product of the percentage saved by the service and the percentage of the cost made up by that service.
 
> *Savings = Service cost percentage * Service cost savings*

### Pourwall
This blog post will center on our analysis of [Pourwall](https://pourwall.com/). Pourwall is a simple and free digital menu system for bars and breweries. It comprises a landing page to inform users about what Pourwall does, a web app to configure menu items and how they are displayed, and an app that runs on TVs to display the menus to customers.

Pourwall runs on cloud infrastructure hosted on AWS. We use S3 to host the website content, such as HTML, CSS, and Javascript files and images. CloudFront is used to distribute this content, RDS to host our database for storing user data, Lambda functions for our backend API, and Cloudwatch for logging. RDS has a fixed monthly cost based on the instance size. Everything else is charged by usage. The more requests we receive, the more we have to pay. 
Pourwall costs were above expected for the number of visitors and devices we had connected. We used Cost Explorer to analyze our AWS service usage and costs and determine which AWS services we should focus our efforts on to obtain a cost reduction.

This is easy in Cost Explorer, as it can group our costs by service. The graph below shows how much we spent per day during the previous month on the various AWS services we use.

![Cost breakdown by AWS service](https://media.graphassets.com/zN2DelHIRHCaahA7tygF)

Analyzing this graph, we can easily see that the API Gateway service should be a priority. If we were to save 50% on our API Gateway costs, which make up 49% of our monthly costs, we would lower our final bill by 24.5%. On the other hand, If we lower the Cloudwatch costs by 50%, our final bill would only be 4.5% smaller since Cloudwatch is only 10% of our final bill. This analysis should be redone as you make improvements, as some changes can impact more than one cloud service, making optimizations to other services more worthwhile.

Looking at our breakdown, we see that most of our cost is due to the large number of API requests we handle, as the second most significant cost is AWS Lambda, where we run our API. Next up comes S3, which is also unexpected. While our site is hosted on S3, we also use a CloudFront distribution for the content, so we generally expect CloudFront to cost more than S3. We’ll examine these three services in more detail below. Since the API Gateway service makes up most of our monthly cost, we’ll start there.

### API Gateway
Pourwall uses a REST API Gateway to handle incoming requests to our Lambda function. AWS REST API Gateway has many useful features not available in the newer HTTP API Gateway, such as WAF integration and support for canary releases. It does, however, charge more per request. As of writing, REST API Gateways are billed at US$3.50 per million requests, while HTTP API Gateways are billed at US$1.00 per million requests. If you are not using the additional features, switching to an HTTP API Gateway will be cheaper.

If you use a custom domain name for your existing API, the switch to an HTTP API Gateway is done entirely inside of AWS-managed infrastructure. You won’t have to worry about DNS propagation issues or client-side code changes. Set up a new HTTP API Gateway to behave as your existing REST API Gateway, and then update the custom domain mapping in the console when you are ready to switch.

The graphs below illustrate the effect on our cost of switching from a REST to an HTTP gateway. The daily costs are now, on average, 24.8% of what they previously were. The data below covers an interval of 3 months and includes data before and after this change (and all other changes in this blog post).

![](https://media.graphassets.com/lLhytllhS4ewtnnGmLr0)

Below we can see the number of requests received by both API Gateways during the same period.

![](https://media.graphassets.com/ai8FBjk2TAGFDwMO0DOg)

### Lambda Cost Reduction
AWS Lambda charges are based on the time your function takes to run. There is also a charge for the number of Lambda invocations made. We will leave this out of our discussion as changes to that require changing client code. You are also charged for the amount of memory configured and ephemeral storage, using the formula below:

> *Lambda Cost =Function Run Time  *(Ephemeral Storage Cost + Memory Cost) *

At a first look, lowering your costs when working with Lambda functions can be done by either optimizing code, lowering its runtime, or by optimizing storage and memory sizes. 

Ephemeral storage is available to the function in the /tmp directory and is between 512MB and 10GB. Unless a Lambda function is used to manipulate large files, it should not need more than the minimum value. As for memory, if the function does not request enough memory, it can fail without logging any errors. The Lambda service will log a message after every run with the amount of memory used. In this case, it will log that all available memory was used. Note that it is also possible to use all available memory without any apparent issues. A Lambda function might also be provisioning too much memory. [Cloudwatch Logs Insights](https://console.aws.amazon.com/cloudwatch/) has a sample query you can run to determine how much memory you are over-provisioning.

![](https://media.graphassets.com/audqA6eTICPDmTdDhi90)

```
filter @type = "REPORT" 
| stats max(@memorySize / 1024 / 1024) as provisonedMemoryMB, 
  min(@maxMemoryUsed / 1024 / 1024) as smallestMemoryRequestMB,
  avg(@maxMemoryUsed / 1024 / 1024) as avgMemoryUsedMB,
  max(@maxMemoryUsed / 1024 / 1024) as maxMemoryUsedMB,
  provisonedMemoryMB - maxMemoryUsedMB as overProvisionedMB
```

You can run that query selecting your lambda function log group and a sufficiently significant time interval to determine your maximum over-provisioned memory. Usage may vary throughout the day or on different days. Looking at how many log entries you have can help you determine how much time to look over. 
Over-provisioned memory is only an indicator of whether you should change your memory allocation for a Lambda function. This is because Lambda functions are allocated CPU based on the configured memory. When you alter the available memory for the function, you will also alter the function run time. You should check the effect on the function runtime. Be sure you have enough data for comparison. Cloudwatch metrics also contain data on your lambda duration, which can also be found in the Lambda function logs.

The Pourwall API makes some calls to external APIs, affecting the average duration. Since this depends on which users are online at a given time, we take an average of more than 24 hours of data. Below we reproduce the average durations during a single week of July. If we fail to take into account the high-latency calls, we can end up with an average duration that is up to three times as low. This value will also be directly impacted by increases in memory. This might lead us to maintain (or maybe increase) the overprovisioned memory, even though decreasing it will actually lower cost, in our case.

![](https://media.graphassets.com/n4ZrW34fQb2YMS6ufBZ3)

By using the provided query, we found that around 512 MB of memory was over-provisioned. The table below shows the average durations of our lambda function while varying the configured memory. From the table, we can see that lowering the configured memory by the maximum over-provisioned amount significantly affects the performance, increasing the processing time by 33%. This increase is not enough to affect user experience, and the 50% reduction in cost leads to an overall lower cost. 

![Lambda Duration and Cost for Different Memory Configurations](https://media.graphassets.com/aEgEXOKJTRC7jkbp5PIH)

The graph below shows the average duration after the changes were applied. We can see an increase in the average duration, but this still results in an overall decrease in cost as the amount of memory cut is enough to offset this.

![](https://media.graphassets.com/mOGbtbJFRN2jEtWxXA5i)

Another factor to consider is the concurrency limit. By default, you can run up to 1000 instances of your Lambda function. You can add concurrency limits to your lambda function to make sure that one function will never take up all the available instances and starve other functions. However, once you set a limit, you may start to see throttling when you reach that limit. This is especially true if the limit is too low. Besides generating errors for the clients, this may also impact your costs. Clients may retry a failed request, incurring further processing costs. 

You can see a considerable decrease in throttling after 08/17, when the concurrency limit was increased.

![](https://media.graphassets.com/B5IjthWYTOyFVnHRF0jT)

These combined changes resulted in lower monthly costs for our Lambda function, which can be seen in the graph below. Again, there was no significant change in the number of requests being made during this period.

![](https://media.graphassets.com/bw4Z8tWTQR2nzcq1Zeef)

### S3 Costs

Our service allows users to upload images for backgrounds and other menus. These images are uploaded to an S3 bucket and downloaded by the application website and the TV apps. Our service also allows for the creation of an iframe so users can embed their tap list in another website. The application was using the S3 bucket URLs directly, so all data was being downloaded directly from S3.
Most clients will cache the downloaded images, and response headers will come with a cache-control header. However, client caching is managed by the client application and may not always work. S3 has a logging feature that makes it possible to determine which keys (or files) are being requested. S3 logs are saved to an S3 bucket as multiple CSV files. After joining the data in these files, the below graph was generated. It shows the number of requests for each key over a period of 24 hours. For simplicity, only the top 20 keys were included.

![](https://media.graphassets.com/ALrxLAMSa6qsLd4CYO70)

The top 20 images are being requested at least 800 times a day, with the top image being requested over 5000 times. Using CloudFront for this content is one way to lower costs. When a cached resource is requested, no request is made to S3, lowering the S3 bandwidth cost. This pattern of repeated requests from the same client will be able to use CloudFront caching.
We set up a CloudFront distribution for the uploaded content and altered our application configurations to use the new CloudFront distribution. Our CloudFront distribution uses Price Class 100, which uses edge locations in North America, Europe, and Israel. This is because most of our users are in North America and Europe, and we do not have a very latency-sensitive application. Using the class will also guarantee that the CloudFront bandwidth will be cheaper than the S3 bandwidth.

We can see the effect of the CloudFront distribution on the S3 costs in the graph below, covering the same 3-month period as before. The valley in cost is due to the free tier offered by AWS. During that period, both the S3 and CloudFront bandwidth falls within this tier, and the account incurs no charges.

![](https://media.graphassets.com/seIcU2uKRvSiaVLlXXXW)

### Final Analysis
Below, we reproduce the costs for the same 3-month period as above. The month of September is still missing some data, as it had not yet ended at the time of writing. However, we can clearly see the effect of the changes rolled out in the month of August. API Gateway requests are no longer the largest portion of our bill. It is, in fact, now our third most expensive service, behind Lambda and Cloudwatch. 

![](https://media.graphassets.com/xK1NKmFTSA2BBNR8vWfx)

As mentioned in the beginning, we now have new priorities for cost optimization. We should now continue our focus on Lambda optimizations but also turn an eye to Cloudwatch. In a future blog post, we will dive deeper into how we lowered Lambda costs by getting rid of polling through the use of WebSockets.

Optimizing your AWS Serverless Costs

Best-in class software innovates and evolves to keep customers engaged. One way to improve and add features without disrupting the current user experience is to deploy a canary release.

Canary releases get their name from an old coal mining practice of taking canaries into the mine to test for deadly carbon monoxide. Carbon monoxide is odorless, and would affect a small bird much faster than a miner. So if you were deep in a mine and your canary stopped singing and became sluggish, you knew it was time to get out quickly. Here in the coding world, we can use a similar warning system to test new features and code changes.

## Here’s how it works
When you want to introduce a new feature or code change, you run two different versions of your code in parallel. Most of your users will still be accessing the current version of your site or service – think of them as your miners. Then, a small percentage of users – the canaries – will experience the new version. This allows you to test your new features or changes with real world users while limiting the potential impact of any bugs in the new release.

Once you’re confident that the new version is working as it should, you can then increase the percentage of users using the new version of your code. This slow rollout will allow you to diagnose any scaling issues that might not initially show up with your small test group.

## AWS Cloudfront 
Cloudfront is a Content Delivery Network (CDN) provided by AWS. It helps developers make their sites scale better and with lower latencies by caching site content locally across multiple regions of the world, while only maintaining a single instance of your site. It’s a great tool for developers and is widely used, but AWS Cloudfront doesn’t have native support for canary releases. Fortunately, there’s a workaround: it does have support for running custom code on all requests through Cloudfront Functions and lambda@edge. So let’s talk about how to leverage lambda@edge functions to implement a canary release.

## lambda@edge
The lambda@edge AWS service allows developers to deploy lambda functions to all Cloudfront regions, so they can be called by Cloudfront with low latencies. lambda@edge functions have some different limitations than regular lambda functions, and you can check those out [here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-functions-restrictions.html).

When you associate a lambda@edge function with a Cloudfront distribution, the function version that is associated will be deployed to all regions. This allows for lower latency, but be aware that the logs for the lambda function will be created in the region where the request was handled.

## A Canary Release on Cloudfront
Now, let’s talk details. Hosting a SPA on S3 using Cloudfront as a cache is a simple way to host your site. You can use the static site hosting option from S3 for a public site, or you can keep your S3 bucket private and access the content through Cloudfront using an OAI. If you plan to use an OAI, you’ll probably need to do some editing to the requests with a lambda@edge or a Cloudfront function to handle paths correctly. 

![Untitled.png](https://media.graphassets.com/0UnENPkETv2kQdKHKV0i)

To  run a canary release, just add a lambda@edge function to handle the requests that cloudfront will be making to the origin, in this case the S3 bucket. The code below will change the origin based on the value of the header bucket. This header should be the header used in the cache behavior in Cloudfront. This will reduce the number of times the lambda functions need to be called.

```
"use strict";
exports.handler = (event, context, callback) => {
  const request = event.records[0].cf.request;
  if (request.headers.cookie) {
    request.headers.cookie.foreach(function (cookie) {
      if (cookie.value.startswith("mycookiename=")) {
        const domainname = "new-release-bucket.s3.amazonaws.com";
        request.origin.s3.domainname = domainname;
        request.headers["host"] = [{ key: "host", value: domainname }];
      }
    });
  }
  callback(null, request);
};
```

It’s best practice to set a cookie before making the request, but you can also make use of another function attached to the viewer request or response event to set the cookie. Using a cookie will also keep the user on the new release throughout all the requests made to the site.

## Where can you grow from here?
The great thing about deploying canary releases is that you can dream big and keep risks small. What are some of the features and add-ons your customer’s have been asking for? What are the best-in-class apps doing that you’d like to be doing? What new feature would make your software stand out? Pick one, start coding, and let the canaries lead the way! 

Innovation without Disruption

The Canary Release

Adam

### Overview
Building apps that function well across multiple platforms has been challenging at times, but now there are tools to speed up the process. Flutter is a great option for creating cross-platform apps for iOS, Android, Web, Windows, and macOS. With one codebase you can create a native app for each platform with very little custom code.

Out of the box, the app will look and behave similarly, though not identically, on each platform because Flutter automatically accounts for platform differences via platform adaptations.

> Things that are behaviors of the OS environment (such as text editing and scrolling) and that would be ‘wrong’ if a different behavior took place.
Flutter Docs – [Platform Adaptions](https://docs.flutter.dev/resources/platform-adaptations)

For example, here’s a standard text field in both iOS and Android. The form fields look nearly identical, but the text selection interface is customized per platform.

![Android text selection](https://media.graphassets.com/kuBIOL8kSWGoXI2zfVdU)

![iOS text selection](https://media.graphassets.com/mUk0TCsATk60qRT2EFHg)

### Platform Aware
In many projects, you’ll want iOS users to see the more familiar iOS design system. To do this, you’ll want to use platform aware widgets. These widgets are aware of what platform they’re being displayed on and will render the UI that’s appropriate.  Let’s take a look at the three ways you can put platform aware widgets to work in Flutter.

### Flutter’s Built-in Adaptive Widgets
Flutter has some built-in ‘adaptive’ widgets which automatically render appropriately for iOS and Android. For example, the standard Icon widget renders the same icon for both platforms.

```
Icon(Icons.share);
```

![standard Flutter icons](https://media.graphassets.com/24vavxbpRwiCAtMXN7ss)

But if you use the adaptive version, it will render the appropriate version for each OS.

```
Icon(Icons.adaptive.share);
```

![adaptive Flutter icons](https://media.graphassets.com/XK9UCLYDTEeXuKSikGaL)

### Roll Your Own Adaptive Widgets
If Flutter doesn’t offer the adaptive widget you need, you can create your own pretty easily. Check the OS via the Platform class and return the appropriate widget.

```
 _makeSlider() {
      if (Platform.isAndroid) {
        return Slider(
          min: 0,
          max: 10,
          value: 1,
          onChanged: (val) => print(val),
        );
      } else if (Platform.isIOS) {
        return CupertinoSlider(
          min: 0,
          max: 10,
          value: 1,
          onChanged: (val) => print(val),
        );
      }
    }
```

![Material and Cupertino version of a Slider](https://media.graphassets.com/n5fjEiDQTGIhPXvFAlUS)

While rolling your own adaptive widgets does work,  it has a downside. If you go this route, your code will be littered with these platform checks and be difficult to maintain.

### *flutter_platform_widgets*
Luckily, there’s a package available that solves this problem. [flutter_platform_widgets](https://pub.dev/packages/flutter_platform_widgets) offers 23 platform aware widgets and has done the work to make sure they integrate well together.

To get started just call

```flutter pub add flutter_platform_widgets```

Here is the code for both the platform aware and unaware components.

```
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_platform_widgets/flutter_platform_widgets.dart';
import 'package:platformaware/screens/aware_home_screen.dart';

class AwareApp extends StatelessWidget {
  const AwareApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return const PlatformApp(
      localizationsDelegates: [
        DefaultMaterialLocalizations.delegate,
        DefaultWidgetsLocalizations.delegate,
        DefaultCupertinoLocalizations.delegate,
      ],
      home: AwareHomeScreen(),
    );
  }
}
```
[aware_app.dart](https://gist.github.com/adamontherun/cda3afcf74308f5219671c14846b1a5d#file-aware_app-dart)
```
import 'package:flutter/material.dart';
import 'package:flutter_platform_widgets/flutter_platform_widgets.dart';
import 'package:platformaware/screens/dummy_screen.dart';

class AwareHomeScreen extends StatelessWidget {
  const AwareHomeScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return PlatformScaffold(
      appBar:
          PlatformAppBar(title: const Text('Platform Demo'), trailingActions: [
        PlatformIconButton(
            onPressed: () {
              Navigator.push(
                  context,
                  platformPageRoute(
                    context: context,
                    builder: (_) => const DummyScreen(),
                  ));
            },
            icon: const Icon(Icons.add))
      ]),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            PlatformTextField(
              hintText: 'First name',
            ),
            PlatformSwitch(value: true, onChanged: (value) => print('update')),
            PlatformSlider(
              min: 0,
              max: 10,
              value: 1,
              onChanged: (val) => print(val),
            ),
            PlatformTextButton(
                onPressed: () {
                  showPlatformDatePicker(
                    context: context,
                    initialDate: DateTime.now(),
                    firstDate:
                        DateTime.now().subtract(const Duration(days: 1000)),
                    lastDate: DateTime.now().add(const Duration(days: 1000)),
                  );
                },
                child: const Text('choose date')),
            PlatformTextButton(
              onPressed: (() {
                showPlatformDialog(
                  context: context,
                  builder: (_) => PlatformAlertDialog(
                    title: const Text('Alert'),
                    content: const Text('Some content'),
                    actions: <Widget>[
                      PlatformDialogAction(
                        child: PlatformText('Enable'),
                        onPressed: () => Navigator.pop(context),
                      ),
                      PlatformDialogAction(
                        child: PlatformText('Disable'),
                        onPressed: () => Navigator.pop(context),
                      ),
                    ],
                  ),
                );
              }),
              child: const Text('show a dialog'),
            ),
            PlatformPopupMenu(
                options: [
                  PopupMenuOption(
                    label: 'Option One',
                  ),
                  PopupMenuOption(
                    label: 'Option Two',
                  ),
                  PopupMenuOption(
                    label: 'Option Three',
                  )
                ],
                icon: const Icon(
                  Icons.more_horiz,
                )),
          ],
        ),
      ),
    );
  }
}
```
[aware_home_screen.dart](https://gist.github.com/adamontherun/cda3afcf74308f5219671c14846b1a5d#file-aware_home_screen-dart)
```
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:platformaware/screens/unaware_home_screen.dart';

class UnawareApp extends StatelessWidget {
  const UnawareApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      localizationsDelegates: [
        DefaultMaterialLocalizations.delegate,
        DefaultWidgetsLocalizations.delegate,
        DefaultCupertinoLocalizations.delegate,
      ],
      home: UnawareHomeScreen(),
    );
  }
}
```
[unaware_app.dart](https://gist.github.com/adamontherun/cda3afcf74308f5219671c14846b1a5d#file-unaware_app-dart)
```
import 'package:flutter/material.dart';
import 'package:platformaware/screens/dummy_screen.dart';

class UnawareHomeScreen extends StatelessWidget {
  const UnawareHomeScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Platform Demo'), actions: [
        IconButton(
            onPressed: () {
              Navigator.push(
                context,
                MaterialPageRoute(builder: (context) => const DummyScreen()),
              );
            },
            icon: const Icon(Icons.add))
      ]),
      body: Padding(
        padding: const EdgeInsets.all(20.0),
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            const TextField(
              decoration: InputDecoration(
                hintText: 'First name',
              ),
            ),
            Switch(value: true, onChanged: (value) => print('update')),
            Slider(
              min: 0,
              max: 10,
              value: 1,
              onChanged: (val) => print(val),
            ),
            ElevatedButton(
                onPressed: () {
                  showDatePicker(
                    context: context,
                    initialDate: DateTime.now(),
                    firstDate:
                        DateTime.now().subtract(const Duration(days: 1000)),
                    lastDate: DateTime.now().add(const Duration(days: 1000)),
                  );
                },
                child: const Text('choose date')),
            ElevatedButton(
                onPressed: () {
                  showDialog(
                      context: context,
                      builder: ((context) {
                        return AlertDialog(
                          title: const Text('alert!'),
                          content: const Text('some alert content'),
                          actions: [
                            TextButton(
                              child: const Text('Disable'),
                              onPressed: () {
                                Navigator.of(context).pop();
                              },
                            ),
                            TextButton(
                              child: const Text('Enable'),
                              onPressed: () {
                                Navigator.of(context).pop();
                              },
                            ),
                          ],
                        );
                      }));
                },
                child: const Text('show an alert')),
            PopupMenuButton(
              itemBuilder: (context) {
                return const [
                  PopupMenuItem(
                    child: Text('one'),
                  ),
                  PopupMenuItem(
                    child: Text('two'),
                  ),
                  PopupMenuItem(
                    child: Text('three'),
                  ),
                ];
              },
            ),
          ],
        ),
      ),
    );
  }
}
```
[unaware_home_screen.dart](https://gist.github.com/adamontherun/cda3afcf74308f5219671c14846b1a5d#file-unaware_home_screen-dart)

Let’s take a look at the difference when you use a platform aware widget. Here’s a  version that’s not platform aware. Notice there are some minor differences, but overall its similar though  looks a little ‘off’ for iOS.

![video: Standard platform unaware version](https://media.graphassets.com/B3yQivcQfeNSH0t846Qw)

Now let’s look at  the app updated to use the *flutter_platform_widgets* components with no other changes. Notice that the Android version looks the same, but the iOS version looks like a typical iOS app.

![video: flutter_platform_widgets platform aware version](https://media.graphassets.com/uAF3mbsSSsm4T99yD5ag)

The *flutter_platform_widgets* package offers the ability to both extend and theme all of these components. With just a little extra work, your Flutter app can look at home on both iOS and Android, creating a seamless experience for every user.